The API contract

Generated from the API’s OpenAPI document. Field names, required flags and types below come from the same snapshot as the downloadable spec.

Source revision cb7d67b. Download OpenAPI JSON. This snapshot has bearer authentication and no confirmed production servers URL.

`POST /v1/auth/signup`

Signup

Public: no bearer token required.

Request body

Generated from OpenAPI
Field	Required	Type	Constraints
email	Yes	string	{"maxLength":254}
password	Yes	string	{"maxLength":1024,"minLength":12}
account_name	Yes	string	{"maxLength":200,"minLength":1}

Responses

201 — Successful Response SessionOut

422 — Validation Error HTTPValidationError

`POST /v1/auth/login`

Public: no bearer token required.

Request body

Generated from OpenAPI
Field	Required	Type	Constraints
email	Yes	string	{"maxLength":254}
password	Yes	string	{"maxLength":1024,"minLength":1}

Responses

200 — Successful Response SessionOut

422 — Validation Error HTTPValidationError

`POST /v1/auth/logout`

Logout

Authorization: Bearer token required. Account management requires a session and appropriate permissions.

Ends the session that made this request, and only that one. Signing out of one browser must not sign you out of the others.

Generated from OpenAPI
Parameter	Location	Required	Type
authorization	header	No	string \| null

Responses

204 — Successful Response

422 — Validation Error HTTPValidationError

`GET /v1/me`

Authorization: Bearer token required. Account management requires a session and appropriate permissions.

Generated from OpenAPI
Parameter	Location	Required	Type
authorization	header	No	string \| null

Responses

200 — Successful Response MeOut

422 — Validation Error HTTPValidationError

`POST /v1/api-keys`

Create Key

Authorization: Bearer token required. Account management requires a session and appropriate permissions.

Mints a key and shows it once. Reserved to an owner: a key outlives the person and the session that made it, so issuing one is an act of delegation and belongs to whoever owns the bill.

Generated from OpenAPI
Parameter	Location	Required	Type
authorization	header	No	string \| null

Request body

Generated from OpenAPI
Field	Required	Type	Constraints
name	Yes	string	{"maxLength":200,"minLength":1}
scopes	No	string[]	{}

Responses

201 — Successful Response CreatedKeyOut

422 — Validation Error HTTPValidationError

`GET /v1/api-keys`

List Keys

Authorization: Bearer token required. Account management requires a session and appropriate permissions.

Prefixes, never secrets. There is no hash in the response and no way back to the key from anything in it.

Generated from OpenAPI
Parameter	Location	Required	Type
authorization	header	No	string \| null

Responses

200 — Successful Response KeyOut[]

422 — Validation Error HTTPValidationError

`DELETE /v1/api-keys/{key_id}`

Revoke Key

Authorization: Bearer token required. Account management requires a session and appropriate permissions.

Revoking an already-revoked key succeeds. The caller asked for it to stop working and it does not work. A key belonging to another account is a 404, indistinguishable from one that never existed.

Generated from OpenAPI
Parameter	Location	Required	Type
key_id	path	Yes	string (uuid)
authorization	header	No	string \| null

Responses

204 — Successful Response

422 — Validation Error HTTPValidationError

`GET /v1/usage`

Usage

Authorization: Bearer token required. Account management requires a session and appropriate permissions.

The ledger, newest first. `amount` is the delta applied to the balance, so summing the column reconciles against it — a reserve is negative, a refund positive.

Generated from OpenAPI
Parameter	Location	Required	Type
limit	query	No	integer
authorization	header	No	string \| null

Responses

200 — Successful Response UsageEntry[]

422 — Validation Error HTTPValidationError

`POST /v1/profile-searches`

Create Profile Search

Authorization: Bearer token required. Account management requires a session and appropriate permissions.

Generated from OpenAPI
Parameter	Location	Required	Type
Idempotency-Key	header	No	string \| null
authorization	header	No	string \| null

Request body

Generated from OpenAPI
Field	Required	Type	Constraints
search_query	No	string \| null	{}
locations	No	string[]	{"maxItems":100}
exclude_locations	No	string[]	{"maxItems":100}
current_job_titles	No	string[]	{"maxItems":100}
past_job_titles	No	string[]	{"maxItems":100}
exclude_current_job_titles	No	string[]	{"maxItems":100}
exclude_past_job_titles	No	string[]	{"maxItems":100}
current_companies	No	string[]	{"maxItems":100}
past_companies	No	string[]	{"maxItems":100}
exclude_current_companies	No	string[]	{"maxItems":100}
exclude_past_companies	No	string[]	{"maxItems":100}
schools	No	string[]	{"maxItems":100}
exclude_schools	No	string[]	{"maxItems":100}
industry_ids	No	string[]	{"maxItems":100}
exclude_industry_ids	No	string[]	{"maxItems":100}
function_ids	No	string[]	{"maxItems":100}
exclude_function_ids	No	string[]	{"maxItems":100}
seniority_ids	No	string[]	{"maxItems":100}
exclude_seniority_ids	No	string[]	{"maxItems":100}
years_of_experience	No	string[]	{"maxItems":100}
years_at_current_company	No	string[]	{"maxItems":100}
company_headcount	No	string[]	{"maxItems":100}
company_hq_locations	No	string[]	{"maxItems":100}
exclude_company_hq_locations	No	string[]	{"maxItems":100}
first_names	No	string[]	{"maxItems":100}
last_names	No	string[]	{"maxItems":100}
profile_languages	No	string[]	{"maxItems":100}
recently_changed_jobs	No	boolean \| null	{}
recently_posted	No	boolean \| null	{}
max_items	No	integer	{"maximum":2000,"minimum":25,"description":"Profiles to fetch. A multiple of 25: the search is served and billed in blocks of 25 whether or not the whole block is taken, so asking for 30 would pay for 50.","default":100}
start_page	No	integer	{"maximum":10000,"minimum":1,"description":"Which page of the result set to start from. NOT a stable cursor: the underlying ordering shifts between calls, so consecutive pages can overlap or skip. Prefer one call with a high max_items over several with paging.","default":1}
label	No	string \| null	{}
webhook_url	No	string \| null	{}

Responses

202 — Successful Response RunAccepted

422 — Validation Error HTTPValidationError

`POST /v1/profile-lookups`

Create Profile Lookup

Authorization: Bearer token required. Account management requires a session and appropriate permissions.

Generated from OpenAPI
Parameter	Location	Required	Type
Idempotency-Key	header	No	string \| null
authorization	header	No	string \| null

Request body

Generated from OpenAPI
Field	Required	Type	Constraints
linkedin_urls	Yes	string[]	{"maxItems":2000,"minItems":1}
label	No	string \| null	{}
webhook_url	No	string \| null	{}

Responses

202 — Successful Response RunAccepted

422 — Validation Error HTTPValidationError

`GET /v1/runs/{run_id}`

Get Run

Authorization: Bearer token required. Account management requires a session and appropriate permissions.

Generated from OpenAPI
Parameter	Location	Required	Type
run_id	path	Yes	string (uuid)
authorization	header	No	string \| null

Responses

200 — Successful Response RunDetail

422 — Validation Error HTTPValidationError

`POST /v1/runs/{run_id}/cancel`

Cancel Run

Authorization: Bearer token required. Account management requires a session and appropriate permissions.

Stop a run that has not finished. Cancelling releases the whole reservation: the run delivered nothing, so it bills nothing. Cancelling an already-cancelled run is not an error — a client retrying a request whose response it never saw wants the run's state, not a failure. Cancelling a *finished* one is, because that asks us to undo something that already cost money, and answering 200 would say we had.

Generated from OpenAPI
Parameter	Location	Required	Type
run_id	path	Yes	string (uuid)
authorization	header	No	string \| null

Responses

200 — Successful Response RunDetail

422 — Validation Error HTTPValidationError

`GET /v1/runs/{run_id}/profiles`

List Profiles

Authorization: Bearer token required. Account management requires a session and appropriate permissions.

Generated from OpenAPI
Parameter	Location	Required	Type
run_id	path	Yes	string (uuid)
limit	query	No	integer
cursor	query	No	string \| null
authorization	header	No	string \| null

Responses

200 — Successful Response ProfilePage

422 — Validation Error HTTPValidationError

`GET /v1/runs/{run_id}/profiles.csv`

Profiles Csv

Authorization: Bearer token required. Account management requires a session and appropriate permissions.

Generated from OpenAPI
Parameter	Location	Required	Type
run_id	path	Yes	string (uuid)
authorization	header	No	string \| null

Responses

200 — Successful Response

422 — Validation Error HTTPValidationError

`GET /v1/catalogs/locations`

Locations

Authorization: Bearer token required. Account management requires a session and appropriate permissions.

Generated from OpenAPI
Parameter	Location	Required	Type
q	query	No	string \| null
limit	query	No	integer
authorization	header	No	string \| null

Responses

200 — Successful Response Catalog

422 — Validation Error HTTPValidationError

`GET /v1/catalogs/industries`

Industries

Authorization: Bearer token required. Account management requires a session and appropriate permissions.

Generated from OpenAPI
Parameter	Location	Required	Type
q	query	No	string \| null
limit	query	No	integer
authorization	header	No	string \| null

Responses

200 — Successful Response Catalog

422 — Validation Error HTTPValidationError

`GET /v1/catalogs/schools`

Schools

Authorization: Bearer token required. Account management requires a session and appropriate permissions.

Suggestions, not an allowlist. Unlike locations this list is a curated selection rather than validated coverage, so `schools` accepts values that are not in it. Rejecting every school outside it would refuse most legitimate searches.

Generated from OpenAPI
Parameter	Location	Required	Type
q	query	No	string \| null
limit	query	No	integer
authorization	header	No	string \| null

Responses

200 — Successful Response Catalog

422 — Validation Error HTTPValidationError

`GET /v1/catalogs/company-headcounts`

Company Headcounts

Authorization: Bearer token required. Account management requires a session and appropriate permissions.

Generated from OpenAPI
Parameter	Location	Required	Type
authorization	header	No	string \| null

Responses

200 — Successful Response Catalog

422 — Validation Error HTTPValidationError

`GET /v1/catalogs/experience-bands`

Experience Bands

Authorization: Bearer token required. Account management requires a session and appropriate permissions.

Generated from OpenAPI
Parameter	Location	Required	Type
authorization	header	No	string \| null

Responses

200 — Successful Response Catalog

422 — Validation Error HTTPValidationError

`GET /v1/demo/profile`

Demo Profile

Public: no bearer token required.

Responses

200 — Successful Response ProfilePage

Models

AccountOut

Generated from OpenAPI
Field	Required	Type	Constraints
account_id	Yes	string (uuid)	{"format":"uuid"}
name	Yes	string	{}
role	Yes	string	{}
balance	Yes	Money	{}
status	Yes	string	{}

Catalog

Generated from OpenAPI
Field	Required	Type	Constraints
data	Yes	CatalogEntry[]	{}
total	Yes	integer	{}
max_per_request	No	integer \| null	{}

CatalogEntry

Generated from OpenAPI
Field	Required	Type	Constraints
value	Yes	string	{}
label	No	string \| null	{}

CreatedKeyOut

Generated from OpenAPI
Field	Required	Type	Constraints
id	Yes	string (uuid)	{"format":"uuid"}
name	Yes	string	{}
key_prefix	Yes	string	{}
scopes	Yes	string[]	{}
created_at	Yes	string (date-time)	{"format":"date-time"}
last_used_at	No	string (date-time) \| null	{}
revoked_at	No	string (date-time) \| null	{}
created_by	No	string \| null	{}
secret	Yes	string	{}

Experience

Generated from OpenAPI
Field	Required	Type	Constraints
ordinal	Yes	integer	{}
position	No	string \| null	{}
company_name	No	string \| null	{}
company_linkedin_url	No	string \| null	{}
employment_type	No	string \| null	{}
workplace_type	No	string \| null	{}
location	No	string \| null	{}
description	No	string \| null	{}
started_on	No	string (date) \| null	{}
ended_on	No	string (date) \| null	{}
is_current	No	boolean	{"default":false}
duration_months	No	integer \| null	{}
duration_text	No	string \| null	{}
skills	No	string[]	{"default":[]}

Failure

Generated from OpenAPI
Field	Required	Type	Constraints
reason	Yes	string	{}
detail	No	string \| null	{}

HTTPValidationError

Generated from OpenAPI
Field	Required	Type	Constraints
detail	No	ValidationError[]	{}

KeyOut

Generated from OpenAPI
Field	Required	Type	Constraints
id	Yes	string (uuid)	{"format":"uuid"}
name	Yes	string	{}
key_prefix	Yes	string	{}
scopes	Yes	string[]	{}
created_at	Yes	string (date-time)	{"format":"date-time"}
last_used_at	No	string (date-time) \| null	{}
revoked_at	No	string (date-time) \| null	{}
created_by	No	string \| null	{}

KeyRequest

Generated from OpenAPI
Field	Required	Type	Constraints
name	Yes	string	{"maxLength":200,"minLength":1}
scopes	No	string[]	{}

LoginRequest

Generated from OpenAPI
Field	Required	Type	Constraints
email	Yes	string	{"maxLength":254}
password	Yes	string	{"maxLength":1024,"minLength":1}

MeOut

Generated from OpenAPI
Field	Required	Type	Constraints
user_id	Yes	string (uuid)	{"format":"uuid"}
accounts	Yes	AccountOut[]	{}

Money

Generated from OpenAPI
Field	Required	Type	Constraints
micros	Yes	integer	{}
usd	Yes	string	{}
currency	No	string	{"default":"USD"}

Pagination

Generated from OpenAPI
Field	Required	Type	Constraints
total_elements	No	integer \| null	{}
total_pages	No	integer \| null	{}
page_number	No	integer \| null	{}
page_size	No	integer \| null	{}

ProfileLookupRequest

Generated from OpenAPI
Field	Required	Type	Constraints
linkedin_urls	Yes	string[]	{"maxItems":2000,"minItems":1}
label	No	string \| null	{}
webhook_url	No	string \| null	{}

ProfileOut

Generated from OpenAPI
Field	Required	Type	Constraints
id	Yes	string (uuid)	{"format":"uuid"}
ordinal	Yes	integer	{}
public_identifier	No	string \| null	{}
linkedin_url	Yes	string	{}
requested_url	No	string \| null	{}
first_name	No	string \| null	{}
last_name	No	string \| null	{}
full_name	No	string \| null	{}
headline	No	string \| null	{}
about	No	string \| null	{}
location_text	No	string \| null	{}
location_city	No	string \| null	{}
location_state	No	string \| null	{}
location_region_code	No	string \| null	{}
location_country	No	string \| null	{}
location_country_full	No	string \| null	{}
location_country_code	No	string \| null	{}
open_to_work	No	boolean \| null	{}
hiring	No	boolean \| null	{}
premium	No	boolean \| null	{}
influencer	No	boolean \| null	{}
creator	No	boolean \| null	{}
verified	No	boolean \| null	{}
open_profile	No	boolean \| null	{}
memorialized	No	boolean \| null	{}
connections_count	No	integer \| null	{}
follower_count	No	integer \| null	{}
registered_at	No	string (date-time) \| null	{}
profile_language	No	string \| null	{}
profile_country	No	string \| null	{}
profile_picture_url	No	string \| null	{}
photo_url	No	string \| null	{}
cover_picture_url	No	string \| null	{}
current_title	No	string \| null	{}
current_company_name	No	string \| null	{}
current_company_linkedin_url	No	string \| null	{}
current_position_started_on	No	string (date) \| null	{}
total_months_experience	No	integer \| null	{}
months_at_current_company	No	integer \| null	{}
months_in_current_role	No	integer \| null	{}
promoted_at_current_company	No	boolean	{"default":false}
promotions_count	No	integer	{"default":0}
companies_count	No	integer	{"default":0}
avg_months_per_company	No	integer \| null	{}
linkedin_member_since	No	string (date) \| null	{}
skills_flat	No	string[]	{"default":[]}
languages_flat	No	string[]	{"default":[]}
school_names	No	string[]	{"default":[]}
company_names	No	string[]	{"default":[]}
section_totals	No	object \| null	{}
experience_truncated	No	boolean	{"default":false}
skills_truncated	No	boolean	{"default":false}
education	No	any[]	{"default":[]}
certifications	No	any[]	{"default":[]}
languages	No	any[]	{"default":[]}
skills	No	any[]	{"default":[]}
projects	No	any[]	{"default":[]}
publications	No	any[]	{"default":[]}
courses	No	any[]	{"default":[]}
honors	No	any[]	{"default":[]}
volunteering	No	any[]	{"default":[]}
recommendations	No	any[]	{"default":[]}
interests	No	any[]	{"default":[]}
patents	No	any[]	{"default":[]}
organizations	No	any[]	{"default":[]}
websites	No	any[]	{"default":[]}
top_skills	No	any[]	{"default":[]}
experiences	No	Experience[]	{"default":[]}
scraped_at	Yes	string (date-time)	{"format":"date-time"}

ProfilePage

Generated from OpenAPI
Field	Required	Type	Constraints
data	Yes	ProfileOut[]	{}
has_more	Yes	boolean	{}
next_cursor	No	string \| null	{}

ProfileSearchRequest

Generated from OpenAPI
Field	Required	Type	Constraints
search_query	No	string \| null	{}
locations	No	string[]	{"maxItems":100}
exclude_locations	No	string[]	{"maxItems":100}
current_job_titles	No	string[]	{"maxItems":100}
past_job_titles	No	string[]	{"maxItems":100}
exclude_current_job_titles	No	string[]	{"maxItems":100}
exclude_past_job_titles	No	string[]	{"maxItems":100}
current_companies	No	string[]	{"maxItems":100}
past_companies	No	string[]	{"maxItems":100}
exclude_current_companies	No	string[]	{"maxItems":100}
exclude_past_companies	No	string[]	{"maxItems":100}
schools	No	string[]	{"maxItems":100}
exclude_schools	No	string[]	{"maxItems":100}
industry_ids	No	string[]	{"maxItems":100}
exclude_industry_ids	No	string[]	{"maxItems":100}
function_ids	No	string[]	{"maxItems":100}
exclude_function_ids	No	string[]	{"maxItems":100}
seniority_ids	No	string[]	{"maxItems":100}
exclude_seniority_ids	No	string[]	{"maxItems":100}
years_of_experience	No	string[]	{"maxItems":100}
years_at_current_company	No	string[]	{"maxItems":100}
company_headcount	No	string[]	{"maxItems":100}
company_hq_locations	No	string[]	{"maxItems":100}
exclude_company_hq_locations	No	string[]	{"maxItems":100}
first_names	No	string[]	{"maxItems":100}
last_names	No	string[]	{"maxItems":100}
profile_languages	No	string[]	{"maxItems":100}
recently_changed_jobs	No	boolean \| null	{}
recently_posted	No	boolean \| null	{}
max_items	No	integer	{"maximum":2000,"minimum":25,"description":"Profiles to fetch. A multiple of 25: the search is served and billed in blocks of 25 whether or not the whole block is taken, so asking for 30 would pay for 50.","default":100}
start_page	No	integer	{"maximum":10000,"minimum":1,"description":"Which page of the result set to start from. NOT a stable cursor: the underlying ordering shifts between calls, so consecutive pages can overlap or skip. Prefer one call with a high max_items over several with paging.","default":1}
label	No	string \| null	{}
webhook_url	No	string \| null	{}

RunAccepted

Generated from OpenAPI
Field	Required	Type	Constraints
run_id	Yes	string (uuid)	{"format":"uuid"}
status	Yes	string	{}
mode	Yes	string	{}
resource_type	Yes	string	{}
start_page	Yes	integer	{}
max_items	Yes	integer	{}
webhook_url	Yes	string \| null	{}
created_at	Yes	string (date-time)	{"format":"date-time"}

RunDetail

Generated from OpenAPI
Field	Required	Type	Constraints
run_id	Yes	string (uuid)	{"format":"uuid"}
status	Yes	string	{}
mode	Yes	string	{}
resource_type	Yes	string	{}
label	No	string \| null	{}
input	Yes	object	{"additionalProperties":true}
start_page	Yes	integer	{}
max_items	Yes	integer	{}
profiles_delivered	Yes	integer	{}
duplicates_discarded	Yes	integer	{}
charged	Yes	Money	{}
pagination	Yes	Pagination	{}
failure	No	Failure \| null	{}
unresolved	No	Unresolved[]	{"default":[]}
created_at	Yes	string (date-time)	{"format":"date-time"}
started_at	No	string (date-time) \| null	{}
finished_at	No	string (date-time) \| null	{}
expires_at	Yes	string (date-time)	{"format":"date-time"}

SessionOut

Generated from OpenAPI
Field	Required	Type	Constraints
session_token	Yes	string	{}
expires_at	Yes	string (date-time)	{"format":"date-time"}
account_id	Yes	string (uuid)	{"format":"uuid"}
role	Yes	string	{}
scopes	Yes	string[]	{}

SignupRequest

Generated from OpenAPI
Field	Required	Type	Constraints
email	Yes	string	{"maxLength":254}
password	Yes	string	{"maxLength":1024,"minLength":12}
account_name	Yes	string	{"maxLength":200,"minLength":1}

Unresolved

Generated from OpenAPI
Field	Required	Type	Constraints
requested_url	No	string \| null	{}
reason	Yes	string	{}
detail	No	string \| null	{}

UsageEntry

Generated from OpenAPI
Field	Required	Type	Constraints
kind	Yes	string	{}
units	Yes	integer	{}
amount	Yes	Money	{}
run_id	No	string (uuid) \| null	{}
created_at	Yes	string (date-time)	{"format":"date-time"}

ValidationError

Generated from OpenAPI
Field	Required	Type	Constraints
loc	Yes	string \| integer[]	{}
msg	Yes	string	{}
type	Yes	string	{}
input	No	any	{}
ctx	No	object	{}