{"openapi":"3.1.0","info":{"title":"Random Profiles API","version":"1.3.0","description":"Generate fake user profiles and companies for seed and test data. Request an API key, then fetch random profiles with photos or companies with logos, 100+ fields each."},"servers":[{"url":"/"}],"paths":{"/v1/keys":{"post":{"summary":"Request an API key (email delivery)","description":"Creates (or re-sends) a free API key. The key is emailed to the address provided — the response body does not contain the key. Use `/v1/keys/instant` if you need the key in the response body (e.g. for AI agents / MCP servers / CLIs that can't read email).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"API key emailed to the provided address","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"400":{"description":"Invalid email"},"429":{"description":"Rate limited"}}}},"/v1/waitlist":{"post":{"summary":"Join the paid-tier waitlist","description":"Capture an email address to notify when Pro/Unlimited launch. Used while BILLING_ENABLED=false. Idempotent by email; re-posting with a different interest updates the stored preference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"interest":{"type":"string","enum":["pro","unlimited","any"],"default":"any"},"source":{"type":"string","description":"Free-form origin label (e.g. 'pricing-page', 'account', 'landing'). Max 64 chars."}}}}}},"responses":{"200":{"description":"Joined the waitlist","content":{"application/json":{"schema":{"type":"object","properties":{"joined":{"type":"boolean"},"status":{"type":"string","enum":["created","updated"]},"interest":{"type":"string"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid email"},"429":{"description":"Rate limited"}}}},"/v1/waitlist/count":{"get":{"summary":"Public waitlist signup count (for social-proof badges)","responses":{"200":{"description":"Non-negative integer","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","minimum":0}}}}}}}}},"/v1/keys/instant":{"post":{"summary":"Claim a free API key and receive it in the response","description":"Creates (or re-returns) a free API key, delivering it directly in the response body. Still sends a receipt email. Designed for non-interactive clients (MCP servers, CLIs, CI) that can't read email. Disposable email domains are rejected. Rate limited per IP.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"Key returned in body and emailed as a receipt","content":{"application/json":{"schema":{"type":"object","required":["key","status"],"properties":{"key":{"type":"string","example":"rp_abc123…"},"status":{"type":"string","enum":["created","existing"]},"email":{"type":"string","format":"email"}}}}}},"400":{"description":"Invalid or disposable email"},"429":{"description":"Rate limited"}}}},"/v1/profiles":{"get":{"summary":"List random profiles","security":[{"apiKey":[]}],"parameters":[{"name":"count","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"description":"Number of profiles to return"},{"name":"photo_size","in":"query","schema":{"type":"integer","enum":[64,128,256,512,1024],"default":1024},"description":"Photo size in pixels"},{"name":"photo_format","in":"query","schema":{"type":"string","enum":["jpg","webp"],"default":"jpg"},"description":"Image format for the `photo` URL. WebP is ~30% smaller with the same perceived quality."},{"name":"fields","in":"query","schema":{"type":"string"},"description":"Comma-separated field groups to return (name,email,phone,identity,bio,social,physical,job,address,financial,network,documents,vehicle,contact,digital,interests,education,photo)"},{"name":"gender","in":"query","schema":{"type":"string","enum":["male","female","non-binary"]},"description":"Filter by gender"},{"name":"country","in":"query","schema":{"type":"string"},"description":"Comma-separated country codes to include (US, GB, DE, FR, AU, BR, JP, IN, NG)"},{"name":"exclude_country","in":"query","schema":{"type":"string"},"description":"Comma-separated country codes to exclude"},{"name":"min_age","in":"query","schema":{"type":"integer"},"description":"Minimum age filter"},{"name":"max_age","in":"query","schema":{"type":"integer"},"description":"Maximum age filter"},{"name":"seed","in":"query","schema":{"type":"integer"},"description":"Seed for deterministic results — same seed returns same profiles"},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"],"default":"json"},"description":"Response format (json or csv)"}],"responses":{"200":{"description":"List of profiles"},"401":{"description":"Invalid or missing API key"},"429":{"description":"Daily request limit reached for your tier"}}}},"/v1/profiles/{uuid}":{"get":{"summary":"Get a profile by UUID","security":[{"apiKey":[]}],"parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Single profile"},"401":{"description":"Invalid or missing API key"},"404":{"description":"Profile not found"},"429":{"description":"Daily request limit reached for your tier"}}}},"/v1/images/random":{"get":{"summary":"Get a random profile photo","security":[{"apiKey":[]}],"parameters":[{"name":"size","in":"query","schema":{"type":"integer","enum":[64,128,256,512,1024],"default":1024}},{"name":"format","in":"query","schema":{"type":"string","enum":["jpg","webp"],"default":"jpg"},"description":"Image encoding. WebP is ~30% smaller than JPG."},{"name":"key","in":"query","description":"API key (alternative to X-API-Key header, for use in img tags)","schema":{"type":"string"}}],"responses":{"200":{"description":"JPEG or WebP image","content":{"image/jpeg":{},"image/webp":{}}},"401":{"description":"Invalid or missing API key"},"429":{"description":"Daily request limit reached"}}}},"/v1/images/{uuid}":{"get":{"summary":"Get a profile photo by UUID","security":[{"apiKey":[]}],"parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"size","in":"query","schema":{"type":"integer","enum":[64,128,256,512,1024],"default":1024}},{"name":"format","in":"query","schema":{"type":"string","enum":["jpg","webp"],"default":"jpg"},"description":"Image encoding. WebP is ~30% smaller than JPG."},{"name":"key","in":"query","description":"API key (alternative to X-API-Key header, for use in img tags)","schema":{"type":"string"}}],"responses":{"200":{"description":"JPEG or WebP image","content":{"image/jpeg":{},"image/webp":{}}},"401":{"description":"Invalid or missing API key"},"404":{"description":"Image not found"},"429":{"description":"Daily request limit reached"}}}},"/v1/billing/usage":{"get":{"summary":"Get usage info for an API key","security":[{"apiKey":[]}],"responses":{"200":{"description":"Usage info including tier, daily limits, and counts"},"401":{"description":"Invalid or missing API key"}}}},"/v1/auth/login":{"post":{"summary":"Send magic link login email","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"Magic link sent (always returns success)"},"400":{"description":"Invalid email"}}}},"/v1/auth/me":{"get":{"summary":"Get current account data","description":"Requires a valid session cookie from magic link login","responses":{"200":{"description":"Account data including email, tier, usage, and keys"},"401":{"description":"Not authenticated or session expired"}}}},"/v1/auth/account":{"delete":{"summary":"Delete the authenticated account (GDPR Art. 17)","description":"Permanently deletes every API key, request log, and session tied to the signed-in email. Requires a valid session cookie. Billing invoices held by the payment processor (Lemon Squeezy) are retained separately under Dutch tax law (7 years).","responses":{"200":{"description":"Account deleted. Returns the number of API keys removed.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"keys_deleted":{"type":"integer"}}}}}},"401":{"description":"Not authenticated or session expired"}}}},"/v1/companies":{"get":{"summary":"List random companies","security":[{"apiKey":[]}],"parameters":[{"name":"count","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"description":"Number of companies to return"},{"name":"fields","in":"query","schema":{"type":"string"},"description":"Comma-separated field groups (name, industry, size, location, contact, social, financial, tech, leadership, legal, operations, product, relationships, meta). The `relationships` group returns employee_uuids — a sample of up to 30 profiles assigned to the company."},{"name":"logo_size","in":"query","schema":{"type":"string","enum":["64","128","256","512","1024"],"default":"1024"},"description":"Size of the `meta.logo_url` variant returned (64, 128, 256, 512, 1024 — default 1024)"},{"name":"logo_format","in":"query","schema":{"type":"string","enum":["jpg","webp"],"default":"jpg"},"description":"Image format for the `meta.logo_url` URL. WebP is ~30% smaller with the same perceived quality."},{"name":"industry","in":"query","schema":{"type":"string"},"description":"Filter by industry"},{"name":"country","in":"query","schema":{"type":"string"},"description":"Comma-separated country codes (US, GB, DE, FR, AU, BR, JP, IN, NG)"},{"name":"size","in":"query","schema":{"type":"string"},"description":"Comma-separated size brackets (1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5000+)"},{"name":"seed","in":"query","schema":{"type":"integer"},"description":"Seed for deterministic results"},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"],"default":"json"},"description":"Response format"}],"responses":{"200":{"description":"List of companies","content":{"application/json":{"schema":{"type":"object","properties":{"companies":{"type":"array","items":{"$ref":"#/components/schemas/Company"}}}}},"text/csv":{"schema":{"type":"string","description":"CSV with flattened nested fields (requires format=csv)"}}}},"401":{"description":"Invalid or missing API key"},"429":{"description":"Daily request limit reached"}}}},"/v1/companies/{uuid}":{"get":{"summary":"Get a company by UUID","security":[{"apiKey":[]}],"parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Single company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"401":{"description":"Invalid or missing API key"},"404":{"description":"Company not found"}}}},"/health":{"get":{"summary":"Health check","responses":{"200":{"description":"Service is healthy"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"X-API-Key","in":"header"}},"schemas":{"Company":{"type":"object","description":"Fake company with 100+ fields grouped into logical blocks selectable via the `fields=` query param.","properties":{"uuid":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Acme Cloud"},"legal_name":{"type":"string","example":"Acme Cloud Inc."},"legal_form":{"type":"string","example":"Inc.","description":"Jurisdiction-specific legal form."},"slug":{"type":"string"},"domain":{"type":"string"},"description":{"type":"string"},"tagline":{"type":"string"},"industry":{"type":"string","enum":["Technology","Healthcare","Finance","Education","Manufacturing","Retail","Media","Consulting","Real Estate","Transportation","Energy","Telecommunications","Hospitality","Agriculture","Legal","Construction"]},"sub_industry":{"type":"string"},"type":{"type":"string","enum":["private","public","nonprofit"]},"size":{"type":"string","enum":["1-10","11-50","51-200","201-500","501-1000","1001-5000","5000+"]},"tags":{"type":"array","items":{"type":"string"}},"location":{"type":"object","properties":{"street":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string","example":"US"},"country_name":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"timezone":{"type":"string"},"locations":{"type":"array","items":{"type":"object","properties":{"city":{"type":"string"},"country":{"type":"string"}}}}}},"contact":{"type":"object","properties":{"phone":{"type":"string"},"fax":{"type":["string","null"]},"toll_free":{"type":["string","null"]},"email":{"type":"string","format":"email"},"support_email":{"type":"string","format":"email"},"sales_email":{"type":"string","format":"email"},"press_email":{"type":"string","format":"email"},"website":{"type":"string","format":"uri"},"languages":{"type":"array","items":{"type":"string"}}}},"social":{"type":"object","properties":{"twitter":{"type":"string"},"linkedin":{"type":"string"},"github":{"type":"string"},"facebook":{"type":"string"},"instagram":{"type":"string"},"youtube":{"type":"string"},"tiktok":{"type":"string"},"mastodon":{"type":"string"},"bluesky":{"type":"string"},"crunchbase":{"type":"string"}}},"financial":{"type":"object","properties":{"revenue_range":{"type":"string"},"revenue_usd":{"type":"number"},"funding_total":{"type":["number","null"]},"valuation":{"type":["number","null"]},"market_cap":{"type":["number","null"]},"ebitda":{"type":"number"},"profit_margin":{"type":"number"},"currency":{"type":"string","example":"USD"},"stock_ticker":{"type":["string","null"]},"ipo_date":{"type":["string","null"],"format":"date"},"last_round":{"type":["string","null"]},"investors":{"type":"array","items":{"type":"string"}},"funding_rounds":{"type":"array","items":{"type":"object","properties":{"round":{"type":"string"},"amount":{"type":"number"},"date":{"type":"string","format":"date"},"lead_investor":{"type":"string"}}}},"fiscal_year_end":{"type":"string"}}},"tech":{"type":"object","properties":{"tech_stack":{"type":"array","items":{"type":"string"}},"frontend":{"type":"array","items":{"type":"string"}},"backend":{"type":"array","items":{"type":"string"}},"database":{"type":"array","items":{"type":"string"}},"cloud":{"type":"array","items":{"type":"string"}},"analytics":{"type":"array","items":{"type":"string"}},"security_certifications":{"type":"array","items":{"type":"string"}},"api_docs_url":{"type":"string","format":"uri"},"status_page_url":{"type":"string","format":"uri"}}},"leadership":{"type":"object","properties":{"ceo_name":{"type":"string"},"ceo_email":{"type":"string","format":"email"},"cfo_name":{"type":"string"},"cto_name":{"type":"string"},"coo_name":{"type":"string"},"founder_names":{"type":"array","items":{"type":"string"}}}},"legal":{"type":"object","properties":{"tax_id":{"type":"string"},"vat_number":{"type":["string","null"]},"duns_number":{"type":"string"},"registration_number":{"type":"string"},"lei":{"type":"string"},"incorporation_state":{"type":"string"}}},"operations":{"type":"object","properties":{"status":{"type":"string","enum":["active","acquired","defunct"]},"is_active":{"type":"boolean"},"parent_company":{"type":["string","null"]},"acquired_by":{"type":["string","null"]},"acquired_date":{"type":["string","null"],"format":"date"},"subsidiaries":{"type":"array","items":{"type":"string"}},"remote_policy":{"type":"string","enum":["remote-first","hybrid","on-site","distributed"]}}},"product":{"type":"object","properties":{"products":{"type":"array","items":{"type":"string"}},"services":{"type":"array","items":{"type":"string"}},"target_market":{"type":"string"},"customer_count":{"type":"integer"},"nps_score":{"type":"integer"},"competitors":{"type":"array","items":{"type":"string"}}}},"relationships":{"type":"object","properties":{"employee_uuids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Up to 30 profile UUIDs assigned to this company. Hydrate via /v1/profiles/:uuid."}}},"meta":{"type":"object","properties":{"logo_url":{"type":"string","format":"uri"},"avatar_url":{"type":"string","format":"uri"},"cover_color":{"type":"string","example":"#3a86ff"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}}