{
  "openapi": "3.1.0",
  "info": {
    "title": "Refolk API",
    "version": "v1",
    "description": "Search for people programmatically. Two searches, one account, one credit balance.\n\nThe agentic search takes a sentence, plans the search itself, reads public sources live, and returns a ranked shortlist with the evidence behind each pick. The structured search takes a filter set and returns a deterministic page of people.\n\nAuthenticate with `Authorization: Bearer rfk_live_...`. Keys are created at https://www.refolk.ai/hire/api.",
    "contact": {
      "name": "Refolk",
      "email": "hello@refolk.ai",
      "url": "https://www.refolk.ai/developers"
    }
  },
  "servers": [
    {
      "url": "https://www.refolk.ai/api/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key from /hire/api. Also accepted as an X-Api-Key header."
      }
    },
    "schemas": {
      "StructuredQuery": {
        "type": "object",
        "description": "A filter set. Every field is optional, but at least one must be set. Fields are combined with AND.",
        "properties": {
          "keywords": {
            "type": "string",
            "description": "Free text matched against the person's headline."
          },
          "titleIncludes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Job titles to include, matched as substrings. e.g. [\"staff engineer\", \"principal engineer\"]."
          },
          "titleExcludes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Job titles to exclude."
          },
          "companyNames": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Employer names. Use the company's common name, not its legal one."
          },
          "companyIndustries": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Industries the employer is in. e.g. [\"Financial Services\"]."
          },
          "seniorityLevels": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "Owner",
                "Founder",
                "CXO",
                "Partner",
                "VP",
                "Director",
                "Manager",
                "Senior",
                "Entry"
              ]
            },
            "description": "Seniority bands. Only these values are accepted."
          },
          "headcountRanges": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "1-10",
                "11-50",
                "51-200",
                "201-500",
                "501-1000",
                "1001-5000",
                "5001-10000",
                "10001+"
              ]
            },
            "description": "Employer size bands. Only these values are accepted."
          },
          "locations": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Metro areas, spelled the way a profile would. e.g. [\"San Francisco Bay Area\"]."
          },
          "countries": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Countries. e.g. [\"United States\", \"Germany\"]."
          },
          "skills": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Skills listed on the profile. e.g. [\"Rust\", \"Kubernetes\"]."
          },
          "minYearsExperience": {
            "type": "number",
            "description": "Lower bound on total years of experience."
          },
          "maxYearsExperience": {
            "type": "number",
            "description": "Upper bound on total years of experience."
          },
          "recentlyChangedJobs": {
            "type": "boolean",
            "description": "Only people who started somewhere new recently."
          },
          "verifiedEmailOnly": {
            "type": "boolean",
            "description": "Only people with a verified work email on file."
          },
          "currentEmployersOnly": {
            "type": "boolean",
            "description": "Match employer filters against the current role only. Defaults to true; set false to match past roles too."
          }
        },
        "additionalProperties": false
      },
      "Person": {
        "type": "object",
        "description": "One person, merged from every source that had something to say about them.",
        "properties": {
          "key": {
            "type": "string",
            "description": "Stable identifier for this person within the run."
          },
          "name": {
            "type": "string"
          },
          "headline": {
            "type": "string"
          },
          "location": {
            "type": "string"
          },
          "currentTitle": {
            "type": "string"
          },
          "currentCompany": {
            "type": "string"
          },
          "currentCompanyDomain": {
            "type": "string"
          },
          "reason": {
            "type": "string",
            "description": "Why this person matched, in one sentence."
          },
          "signals": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The evidence behind the match."
          },
          "githubUrl": {
            "type": "string"
          },
          "linkedinUrl": {
            "type": "string"
          },
          "twitterUrl": {
            "type": "string"
          },
          "avatarUrl": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "skills": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "yearsOfExperience": {
            "type": "number"
          },
          "rank": {
            "type": "number"
          }
        },
        "required": [
          "key",
          "name"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "forbidden",
                  "invalid_request",
                  "insufficient_credits",
                  "rate_limited",
                  "upstream_error",
                  "server_error"
                ]
              },
              "message": {
                "type": "string"
              },
              "balance": {
                "type": "number"
              },
              "retryAfter": {
                "type": "number"
              }
            },
            "required": [
              "type",
              "message"
            ]
          }
        },
        "required": [
          "error"
        ]
      }
    }
  },
  "paths": {
    "/search": {
      "post": {
        "operationId": "agenticSearch",
        "summary": "Search in plain English",
        "description": "Describe who you are looking for and get back a ranked shortlist with the reasoning behind each pick.\n\nReserves 10 credits and reconciles against what the run actually cost, which is usually far less. Set `stream: true` for server-sent events instead of a single JSON body.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "One sentence describing who you want. Use this or `messages`."
                  },
                  "messages": {
                    "type": "array",
                    "description": "A conversation, for follow-ups. Use this or `query`.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "role": {
                          "type": "string",
                          "enum": [
                            "user",
                            "assistant"
                          ]
                        },
                        "content": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "role",
                        "content"
                      ]
                    }
                  },
                  "stream": {
                    "type": "boolean",
                    "description": "Return server-sent events instead of one JSON body."
                  },
                  "rerank": {
                    "type": "boolean",
                    "description": "Rank and trim to a shortlist. Defaults to true; set false for every unique person the sources returned."
                  }
                }
              },
              "examples": {
                "simple": {
                  "summary": "One sentence",
                  "value": {
                    "query": "Staff backend engineers in NYC who shipped Rust in production"
                  }
                },
                "followUp": {
                  "summary": "A follow-up",
                  "value": {
                    "messages": [
                      {
                        "role": "user",
                        "content": "Founders of seed-stage fintechs in London"
                      },
                      {
                        "role": "assistant",
                        "content": "Found 25."
                      },
                      {
                        "role": "user",
                        "content": "Only the ones who were engineers first"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The shortlist.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "answer": {
                      "type": "string",
                      "description": "A short written summary of the run."
                    },
                    "people": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "description": "One person, merged from every source that had something to say about them.",
                        "properties": {
                          "key": {
                            "type": "string",
                            "description": "Stable identifier for this person within the run."
                          },
                          "name": {
                            "type": "string"
                          },
                          "headline": {
                            "type": "string"
                          },
                          "location": {
                            "type": "string"
                          },
                          "currentTitle": {
                            "type": "string"
                          },
                          "currentCompany": {
                            "type": "string"
                          },
                          "currentCompanyDomain": {
                            "type": "string"
                          },
                          "reason": {
                            "type": "string",
                            "description": "Why this person matched, in one sentence."
                          },
                          "signals": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "The evidence behind the match."
                          },
                          "githubUrl": {
                            "type": "string"
                          },
                          "linkedinUrl": {
                            "type": "string"
                          },
                          "twitterUrl": {
                            "type": "string"
                          },
                          "avatarUrl": {
                            "type": "string"
                          },
                          "email": {
                            "type": "string"
                          },
                          "skills": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "yearsOfExperience": {
                            "type": "number"
                          },
                          "rank": {
                            "type": "number"
                          }
                        },
                        "required": [
                          "key",
                          "name"
                        ]
                      }
                    },
                    "companies": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "repos": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "credits": {
                      "type": "object",
                      "properties": {
                        "charged": {
                          "type": "number"
                        },
                        "balance": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "charged",
                        "balance"
                      ]
                    }
                  },
                  "required": [
                    "answer",
                    "people",
                    "companies",
                    "repos",
                    "credits"
                  ]
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "One JSON object per `data:` line. Types: token, step, step_done, people_partial, people, companies, repos, balance, done, error."
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "unauthorized",
                            "forbidden",
                            "invalid_request",
                            "insufficient_credits",
                            "rate_limited",
                            "upstream_error",
                            "server_error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "balance": {
                          "type": "number"
                        },
                        "retryAfter": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "type",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, or revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "unauthorized",
                            "forbidden",
                            "invalid_request",
                            "insufficient_credits",
                            "rate_limited",
                            "upstream_error",
                            "server_error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "balance": {
                          "type": "number"
                        },
                        "retryAfter": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "type",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "402": {
            "description": "Not enough credits.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "unauthorized",
                            "forbidden",
                            "invalid_request",
                            "insufficient_credits",
                            "rate_limited",
                            "upstream_error",
                            "server_error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "balance": {
                          "type": "number"
                        },
                        "retryAfter": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "type",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Read Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "unauthorized",
                            "forbidden",
                            "invalid_request",
                            "insufficient_credits",
                            "rate_limited",
                            "upstream_error",
                            "server_error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "balance": {
                          "type": "number"
                        },
                        "retryAfter": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "type",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "502": {
            "description": "A source failed. Any charge is refunded.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "unauthorized",
                            "forbidden",
                            "invalid_request",
                            "insufficient_credits",
                            "rate_limited",
                            "upstream_error",
                            "server_error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "balance": {
                          "type": "number"
                        },
                        "retryAfter": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "type",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/people/search": {
      "post": {
        "operationId": "structuredSearch",
        "summary": "Search with filters",
        "description": "Deterministic, repeatable, 1 credit a call. Paginate by passing back `nextCursor`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "object",
                    "description": "A filter set. Every field is optional, but at least one must be set. Fields are combined with AND.",
                    "properties": {
                      "keywords": {
                        "type": "string",
                        "description": "Free text matched against the person's headline."
                      },
                      "titleIncludes": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Job titles to include, matched as substrings. e.g. [\"staff engineer\", \"principal engineer\"]."
                      },
                      "titleExcludes": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Job titles to exclude."
                      },
                      "companyNames": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Employer names. Use the company's common name, not its legal one."
                      },
                      "companyIndustries": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Industries the employer is in. e.g. [\"Financial Services\"]."
                      },
                      "seniorityLevels": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "Owner",
                            "Founder",
                            "CXO",
                            "Partner",
                            "VP",
                            "Director",
                            "Manager",
                            "Senior",
                            "Entry"
                          ]
                        },
                        "description": "Seniority bands. Only these values are accepted."
                      },
                      "headcountRanges": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "1-10",
                            "11-50",
                            "51-200",
                            "201-500",
                            "501-1000",
                            "1001-5000",
                            "5001-10000",
                            "10001+"
                          ]
                        },
                        "description": "Employer size bands. Only these values are accepted."
                      },
                      "locations": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Metro areas, spelled the way a profile would. e.g. [\"San Francisco Bay Area\"]."
                      },
                      "countries": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Countries. e.g. [\"United States\", \"Germany\"]."
                      },
                      "skills": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Skills listed on the profile. e.g. [\"Rust\", \"Kubernetes\"]."
                      },
                      "minYearsExperience": {
                        "type": "number",
                        "description": "Lower bound on total years of experience."
                      },
                      "maxYearsExperience": {
                        "type": "number",
                        "description": "Upper bound on total years of experience."
                      },
                      "recentlyChangedJobs": {
                        "type": "boolean",
                        "description": "Only people who started somewhere new recently."
                      },
                      "verifiedEmailOnly": {
                        "type": "boolean",
                        "description": "Only people with a verified work email on file."
                      },
                      "currentEmployersOnly": {
                        "type": "boolean",
                        "description": "Match employer filters against the current role only. Defaults to true; set false to match past roles too."
                      }
                    },
                    "additionalProperties": false
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100,
                    "default": 25
                  },
                  "cursor": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The `nextCursor` from a previous response."
                  }
                },
                "required": [
                  "query"
                ]
              },
              "examples": {
                "seniorRustInGermany": {
                  "summary": "Senior Rust engineers in Germany",
                  "value": {
                    "query": {
                      "titleIncludes": [
                        "engineer"
                      ],
                      "skills": [
                        "Rust"
                      ],
                      "countries": [
                        "Germany"
                      ],
                      "seniorityLevels": [
                        "Senior",
                        "Director"
                      ],
                      "minYearsExperience": 6
                    },
                    "limit": 25
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One page of people.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "profiles": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "totalCount": {
                      "type": "number"
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "credits": {
                      "type": "object",
                      "properties": {
                        "charged": {
                          "type": "number"
                        },
                        "balance": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "charged",
                        "balance"
                      ]
                    }
                  },
                  "required": [
                    "profiles",
                    "totalCount",
                    "nextCursor",
                    "credits"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "unauthorized",
                            "forbidden",
                            "invalid_request",
                            "insufficient_credits",
                            "rate_limited",
                            "upstream_error",
                            "server_error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "balance": {
                          "type": "number"
                        },
                        "retryAfter": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "type",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, or revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "unauthorized",
                            "forbidden",
                            "invalid_request",
                            "insufficient_credits",
                            "rate_limited",
                            "upstream_error",
                            "server_error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "balance": {
                          "type": "number"
                        },
                        "retryAfter": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "type",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "402": {
            "description": "Not enough credits.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "unauthorized",
                            "forbidden",
                            "invalid_request",
                            "insufficient_credits",
                            "rate_limited",
                            "upstream_error",
                            "server_error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "balance": {
                          "type": "number"
                        },
                        "retryAfter": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "type",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Read Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "unauthorized",
                            "forbidden",
                            "invalid_request",
                            "insufficient_credits",
                            "rate_limited",
                            "upstream_error",
                            "server_error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "balance": {
                          "type": "number"
                        },
                        "retryAfter": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "type",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "502": {
            "description": "A source failed. Any charge is refunded.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "unauthorized",
                            "forbidden",
                            "invalid_request",
                            "insufficient_credits",
                            "rate_limited",
                            "upstream_error",
                            "server_error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "balance": {
                          "type": "number"
                        },
                        "retryAfter": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "type",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/people/translate": {
      "post": {
        "operationId": "translateQuery",
        "summary": "Turn a sentence into a filter set",
        "description": "Write the brief once in English, keep the filter set, run it on a schedule. Costs 1 credit.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "prompt": {
                    "type": "string",
                    "description": "Who you are looking for, in English."
                  },
                  "currentQuery": {
                    "type": "object",
                    "description": "An existing filter set to amend rather than replace.",
                    "properties": {
                      "keywords": {
                        "type": "string",
                        "description": "Free text matched against the person's headline."
                      },
                      "titleIncludes": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Job titles to include, matched as substrings. e.g. [\"staff engineer\", \"principal engineer\"]."
                      },
                      "titleExcludes": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Job titles to exclude."
                      },
                      "companyNames": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Employer names. Use the company's common name, not its legal one."
                      },
                      "companyIndustries": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Industries the employer is in. e.g. [\"Financial Services\"]."
                      },
                      "seniorityLevels": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "Owner",
                            "Founder",
                            "CXO",
                            "Partner",
                            "VP",
                            "Director",
                            "Manager",
                            "Senior",
                            "Entry"
                          ]
                        },
                        "description": "Seniority bands. Only these values are accepted."
                      },
                      "headcountRanges": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "1-10",
                            "11-50",
                            "51-200",
                            "201-500",
                            "501-1000",
                            "1001-5000",
                            "5001-10000",
                            "10001+"
                          ]
                        },
                        "description": "Employer size bands. Only these values are accepted."
                      },
                      "locations": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Metro areas, spelled the way a profile would. e.g. [\"San Francisco Bay Area\"]."
                      },
                      "countries": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Countries. e.g. [\"United States\", \"Germany\"]."
                      },
                      "skills": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Skills listed on the profile. e.g. [\"Rust\", \"Kubernetes\"]."
                      },
                      "minYearsExperience": {
                        "type": "number",
                        "description": "Lower bound on total years of experience."
                      },
                      "maxYearsExperience": {
                        "type": "number",
                        "description": "Upper bound on total years of experience."
                      },
                      "recentlyChangedJobs": {
                        "type": "boolean",
                        "description": "Only people who started somewhere new recently."
                      },
                      "verifiedEmailOnly": {
                        "type": "boolean",
                        "description": "Only people with a verified work email on file."
                      },
                      "currentEmployersOnly": {
                        "type": "boolean",
                        "description": "Match employer filters against the current role only. Defaults to true; set false to match past roles too."
                      }
                    },
                    "additionalProperties": false
                  }
                },
                "required": [
                  "prompt"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The filter set.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "object",
                      "description": "A filter set. Every field is optional, but at least one must be set. Fields are combined with AND.",
                      "properties": {
                        "keywords": {
                          "type": "string",
                          "description": "Free text matched against the person's headline."
                        },
                        "titleIncludes": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Job titles to include, matched as substrings. e.g. [\"staff engineer\", \"principal engineer\"]."
                        },
                        "titleExcludes": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Job titles to exclude."
                        },
                        "companyNames": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Employer names. Use the company's common name, not its legal one."
                        },
                        "companyIndustries": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Industries the employer is in. e.g. [\"Financial Services\"]."
                        },
                        "seniorityLevels": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "enum": [
                              "Owner",
                              "Founder",
                              "CXO",
                              "Partner",
                              "VP",
                              "Director",
                              "Manager",
                              "Senior",
                              "Entry"
                            ]
                          },
                          "description": "Seniority bands. Only these values are accepted."
                        },
                        "headcountRanges": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "enum": [
                              "1-10",
                              "11-50",
                              "51-200",
                              "201-500",
                              "501-1000",
                              "1001-5000",
                              "5001-10000",
                              "10001+"
                            ]
                          },
                          "description": "Employer size bands. Only these values are accepted."
                        },
                        "locations": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Metro areas, spelled the way a profile would. e.g. [\"San Francisco Bay Area\"]."
                        },
                        "countries": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Countries. e.g. [\"United States\", \"Germany\"]."
                        },
                        "skills": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Skills listed on the profile. e.g. [\"Rust\", \"Kubernetes\"]."
                        },
                        "minYearsExperience": {
                          "type": "number",
                          "description": "Lower bound on total years of experience."
                        },
                        "maxYearsExperience": {
                          "type": "number",
                          "description": "Upper bound on total years of experience."
                        },
                        "recentlyChangedJobs": {
                          "type": "boolean",
                          "description": "Only people who started somewhere new recently."
                        },
                        "verifiedEmailOnly": {
                          "type": "boolean",
                          "description": "Only people with a verified work email on file."
                        },
                        "currentEmployersOnly": {
                          "type": "boolean",
                          "description": "Match employer filters against the current role only. Defaults to true; set false to match past roles too."
                        }
                      },
                      "additionalProperties": false
                    },
                    "credits": {
                      "type": "object",
                      "properties": {
                        "charged": {
                          "type": "number"
                        },
                        "balance": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "charged",
                        "balance"
                      ]
                    }
                  },
                  "required": [
                    "query",
                    "credits"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "unauthorized",
                            "forbidden",
                            "invalid_request",
                            "insufficient_credits",
                            "rate_limited",
                            "upstream_error",
                            "server_error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "balance": {
                          "type": "number"
                        },
                        "retryAfter": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "type",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, or revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "unauthorized",
                            "forbidden",
                            "invalid_request",
                            "insufficient_credits",
                            "rate_limited",
                            "upstream_error",
                            "server_error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "balance": {
                          "type": "number"
                        },
                        "retryAfter": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "type",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "402": {
            "description": "Not enough credits.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "unauthorized",
                            "forbidden",
                            "invalid_request",
                            "insufficient_credits",
                            "rate_limited",
                            "upstream_error",
                            "server_error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "balance": {
                          "type": "number"
                        },
                        "retryAfter": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "type",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Read Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "unauthorized",
                            "forbidden",
                            "invalid_request",
                            "insufficient_credits",
                            "rate_limited",
                            "upstream_error",
                            "server_error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "balance": {
                          "type": "number"
                        },
                        "retryAfter": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "type",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "502": {
            "description": "A source failed. Any charge is refunded.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "unauthorized",
                            "forbidden",
                            "invalid_request",
                            "insufficient_credits",
                            "rate_limited",
                            "upstream_error",
                            "server_error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "balance": {
                          "type": "number"
                        },
                        "retryAfter": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "type",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/credits": {
      "get": {
        "operationId": "getCredits",
        "summary": "Credit balance",
        "description": "Free to call. Applies the monthly refill if one is due.",
        "responses": {
          "200": {
            "description": "The balance and what each call costs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "balance": {
                      "type": "number",
                      "description": "What is left to spend."
                    },
                    "purchased": {
                      "type": "number",
                      "description": "Bought credits. These survive a refill."
                    },
                    "planCredits": {
                      "type": "number",
                      "description": "The allowance slice, which does not roll over."
                    },
                    "plan": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "name"
                      ]
                    },
                    "monthlyFloor": {
                      "type": "number",
                      "description": "What the allowance refills to each period. Depends on the plan, so read it rather than assuming."
                    },
                    "costs": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "balance",
                    "purchased",
                    "planCredits",
                    "plan",
                    "monthlyFloor",
                    "costs"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, or revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "unauthorized",
                            "forbidden",
                            "invalid_request",
                            "insufficient_credits",
                            "rate_limited",
                            "upstream_error",
                            "server_error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "balance": {
                          "type": "number"
                        },
                        "retryAfter": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "type",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Read Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "unauthorized",
                            "forbidden",
                            "invalid_request",
                            "insufficient_credits",
                            "rate_limited",
                            "upstream_error",
                            "server_error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "balance": {
                          "type": "number"
                        },
                        "retryAfter": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "type",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/me": {
      "get": {
        "operationId": "getMe",
        "summary": "Whose key this is",
        "description": "Free to call. The first thing to try when wiring up a key.",
        "responses": {
          "200": {
            "description": "The account and the key.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "account": {
                      "type": "object"
                    },
                    "key": {
                      "type": "object"
                    },
                    "balance": {
                      "type": "number"
                    }
                  },
                  "required": [
                    "account",
                    "key",
                    "balance"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, or revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "unauthorized",
                            "forbidden",
                            "invalid_request",
                            "insufficient_credits",
                            "rate_limited",
                            "upstream_error",
                            "server_error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "balance": {
                          "type": "number"
                        },
                        "retryAfter": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "type",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Read Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "unauthorized",
                            "forbidden",
                            "invalid_request",
                            "insufficient_credits",
                            "rate_limited",
                            "upstream_error",
                            "server_error"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "balance": {
                          "type": "number"
                        },
                        "retryAfter": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "type",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}