{
  "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. Matched to the index vocabulary, so a near spelling is snapped and the query that ran comes back as `resolvedQuery`."
          },
          "companyIndustries": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Industries the employer is in, matched to the index vocabulary. e.g. [\"Financial Services\"]; \"software\" is snapped to \"Software Development\"."
          },
          "seniorityLevels": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "Owner / Partner",
                "CXO",
                "Vice President",
                "Director",
                "Experienced Manager",
                "Entry Level Manager",
                "Strategic",
                "Senior",
                "Entry Level",
                "In Training"
              ]
            },
            "description": "Seniority bands, as the index spells them. Common shorthand is read as the level it names, so \"VP\" searches for \"Vice President\"."
          },
          "headcountRanges": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "myself only",
                "2-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": "Places, matched to the index vocabulary: a bare city name is snapped to the region a profile is spelled with, so [\"Berlin\"] runs as [\"Berlin, Berlin, Germany\"]. Where one name is several places the most populous wins and the rest are named in `note`, so pass the full string to be sure."
          },
          "countries": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Countries, in full. e.g. [\"United States\", \"Germany\"]. An abbreviation has no entry and matches nothing; `note` says so when that happens."
          },
          "skills": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Skills listed on the profile, matched to the index vocabulary. e.g. [\"Rust\", \"Kubernetes\"]."
          },
          "schools": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Institutions somebody studied at, matched against their education rather than their employers. One school is spelled several ways across profiles, so each value is widened to every spelling of it and the set that ran comes back as `resolvedQuery`: [\"IIT Ropar\"] also searches \"Indian Institute of Technology, Ropar\". Use this for alumni - an employer filter on a university name returns the people who teach there."
          },
          "degrees": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Qualifications, matched to the index vocabulary. e.g. [\"Bachelor of Technology - BTech\", \"Master of Business Administration - MBA\"]."
          },
          "fieldsOfStudy": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "What they studied, matched to the index vocabulary. e.g. [\"Computer Science\"]."
          },
          "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. These are new joiners, not people who are between roles."
          },
          "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\n100 credits a search, flat, whatever the run has to do to answer it. A search that finds nobody is refunded in full. 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, 10 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. Matched to the index vocabulary, so a near spelling is snapped and the query that ran comes back as `resolvedQuery`."
                      },
                      "companyIndustries": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Industries the employer is in, matched to the index vocabulary. e.g. [\"Financial Services\"]; \"software\" is snapped to \"Software Development\"."
                      },
                      "seniorityLevels": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "Owner / Partner",
                            "CXO",
                            "Vice President",
                            "Director",
                            "Experienced Manager",
                            "Entry Level Manager",
                            "Strategic",
                            "Senior",
                            "Entry Level",
                            "In Training"
                          ]
                        },
                        "description": "Seniority bands, as the index spells them. Common shorthand is read as the level it names, so \"VP\" searches for \"Vice President\"."
                      },
                      "headcountRanges": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "myself only",
                            "2-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": "Places, matched to the index vocabulary: a bare city name is snapped to the region a profile is spelled with, so [\"Berlin\"] runs as [\"Berlin, Berlin, Germany\"]. Where one name is several places the most populous wins and the rest are named in `note`, so pass the full string to be sure."
                      },
                      "countries": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Countries, in full. e.g. [\"United States\", \"Germany\"]. An abbreviation has no entry and matches nothing; `note` says so when that happens."
                      },
                      "skills": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Skills listed on the profile, matched to the index vocabulary. e.g. [\"Rust\", \"Kubernetes\"]."
                      },
                      "schools": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Institutions somebody studied at, matched against their education rather than their employers. One school is spelled several ways across profiles, so each value is widened to every spelling of it and the set that ran comes back as `resolvedQuery`: [\"IIT Ropar\"] also searches \"Indian Institute of Technology, Ropar\". Use this for alumni - an employer filter on a university name returns the people who teach there."
                      },
                      "degrees": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Qualifications, matched to the index vocabulary. e.g. [\"Bachelor of Technology - BTech\", \"Master of Business Administration - MBA\"]."
                      },
                      "fieldsOfStudy": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "What they studied, matched to the index vocabulary. e.g. [\"Computer Science\"]."
                      },
                      "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. These are new joiners, not people who are between roles."
                      },
                      "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. Matched to the index vocabulary, so a near spelling is snapped and the query that ran comes back as `resolvedQuery`."
                      },
                      "companyIndustries": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Industries the employer is in, matched to the index vocabulary. e.g. [\"Financial Services\"]; \"software\" is snapped to \"Software Development\"."
                      },
                      "seniorityLevels": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "Owner / Partner",
                            "CXO",
                            "Vice President",
                            "Director",
                            "Experienced Manager",
                            "Entry Level Manager",
                            "Strategic",
                            "Senior",
                            "Entry Level",
                            "In Training"
                          ]
                        },
                        "description": "Seniority bands, as the index spells them. Common shorthand is read as the level it names, so \"VP\" searches for \"Vice President\"."
                      },
                      "headcountRanges": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "myself only",
                            "2-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": "Places, matched to the index vocabulary: a bare city name is snapped to the region a profile is spelled with, so [\"Berlin\"] runs as [\"Berlin, Berlin, Germany\"]. Where one name is several places the most populous wins and the rest are named in `note`, so pass the full string to be sure."
                      },
                      "countries": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Countries, in full. e.g. [\"United States\", \"Germany\"]. An abbreviation has no entry and matches nothing; `note` says so when that happens."
                      },
                      "skills": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Skills listed on the profile, matched to the index vocabulary. e.g. [\"Rust\", \"Kubernetes\"]."
                      },
                      "schools": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Institutions somebody studied at, matched against their education rather than their employers. One school is spelled several ways across profiles, so each value is widened to every spelling of it and the set that ran comes back as `resolvedQuery`: [\"IIT Ropar\"] also searches \"Indian Institute of Technology, Ropar\". Use this for alumni - an employer filter on a university name returns the people who teach there."
                      },
                      "degrees": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Qualifications, matched to the index vocabulary. e.g. [\"Bachelor of Technology - BTech\", \"Master of Business Administration - MBA\"]."
                      },
                      "fieldsOfStudy": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "What they studied, matched to the index vocabulary. e.g. [\"Computer Science\"]."
                      },
                      "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. These are new joiners, not people who are between roles."
                      },
                      "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. Matched to the index vocabulary, so a near spelling is snapped and the query that ran comes back as `resolvedQuery`."
                        },
                        "companyIndustries": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Industries the employer is in, matched to the index vocabulary. e.g. [\"Financial Services\"]; \"software\" is snapped to \"Software Development\"."
                        },
                        "seniorityLevels": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "enum": [
                              "Owner / Partner",
                              "CXO",
                              "Vice President",
                              "Director",
                              "Experienced Manager",
                              "Entry Level Manager",
                              "Strategic",
                              "Senior",
                              "Entry Level",
                              "In Training"
                            ]
                          },
                          "description": "Seniority bands, as the index spells them. Common shorthand is read as the level it names, so \"VP\" searches for \"Vice President\"."
                        },
                        "headcountRanges": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "enum": [
                              "myself only",
                              "2-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": "Places, matched to the index vocabulary: a bare city name is snapped to the region a profile is spelled with, so [\"Berlin\"] runs as [\"Berlin, Berlin, Germany\"]. Where one name is several places the most populous wins and the rest are named in `note`, so pass the full string to be sure."
                        },
                        "countries": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Countries, in full. e.g. [\"United States\", \"Germany\"]. An abbreviation has no entry and matches nothing; `note` says so when that happens."
                        },
                        "skills": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Skills listed on the profile, matched to the index vocabulary. e.g. [\"Rust\", \"Kubernetes\"]."
                        },
                        "schools": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Institutions somebody studied at, matched against their education rather than their employers. One school is spelled several ways across profiles, so each value is widened to every spelling of it and the set that ran comes back as `resolvedQuery`: [\"IIT Ropar\"] also searches \"Indian Institute of Technology, Ropar\". Use this for alumni - an employer filter on a university name returns the people who teach there."
                        },
                        "degrees": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Qualifications, matched to the index vocabulary. e.g. [\"Bachelor of Technology - BTech\", \"Master of Business Administration - MBA\"]."
                        },
                        "fieldsOfStudy": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "What they studied, matched to the index vocabulary. e.g. [\"Computer Science\"]."
                        },
                        "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. These are new joiners, not people who are between roles."
                        },
                        "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"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}