{"openapi":"3.1.0","info":{"title":"LeadsAgent API","description":"Give LeadsAgent a task in plain language, follow its progress, answer its questions and read the leads it finds.","version":"2.0.0"},"servers":[{"url":"http://127.0.0.1:8001/api/v1"}],"paths":{"/tasks":{"post":{"tags":["Tasks"],"summary":"Start a task","description":"Describe what to find in plain language. Returns the task with its status.","operationId":"start_task_tasks_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskInput"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEnvelope_TaskView_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["Tasks"],"summary":"List tasks","operationId":"list_tasks_tasks_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":20,"title":"Limit"}},{"name":"before","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Before"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/tasks/{task_id}":{"get":{"tags":["Tasks"],"summary":"Get a task","description":"Status, the steps taken so far, any pending question, the agent's reply and the lead count.","operationId":"get_task_tasks__task_id__get","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEnvelope_TaskView_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/tasks/{task_id}/messages":{"post":{"tags":["Tasks"],"summary":"Reply to a task","description":"Answer a pending question with `answers`, or continue a finished task with `message`.","operationId":"reply_tasks__task_id__messages_post","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplyBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEnvelope_TaskView_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/tasks/{task_id}/cancel":{"post":{"tags":["Tasks"],"summary":"Stop a task","operationId":"cancel_task_tasks__task_id__cancel_post","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEnvelope_TaskView_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/tasks/{task_id}/results":{"get":{"tags":["Results"],"summary":"Read leads","description":"A page of the leads the task saved. Filter with has_email, has_website, has_phone; follow next_cursor.","operationId":"get_results_tasks__task_id__results_get","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Id"}},{"name":"fields","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fields"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":50,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"has_email","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Email"}},{"name":"has_website","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Website"}},{"name":"has_phone","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Phone"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEnvelope_ResultsPage_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/tasks/{task_id}/export":{"get":{"tags":["Results"],"summary":"Download all leads","description":"Every lead the task saved, as CSV or JSON.","operationId":"export_tasks__task_id__export_get","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Id"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","default":"csv","title":"Format"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/downloads/{token}":{"get":{"tags":["Results"],"summary":"Download a lead list by signed link","description":"The download_url a task gives. No credential needed; the link expires after one hour.","operationId":"download_downloads__token__get","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","title":"Token"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","default":"csv","title":"Format"}},{"name":"filename","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filename"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/find":{"post":{"tags":["Tasks"],"summary":"Find leads","description":"A structured search with yes/no steps and conditions. It runs without the agent.","operationId":"find_find_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindLeadsInput"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEnvelope_TaskView_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/tools":{"get":{"tags":["Tools"],"summary":"Search tools","description":"Find the tools that run on a task's lead list.","operationId":"search_tools_tools_get","parameters":[{"name":"query","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Query"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":8,"minimum":1,"default":3,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/tasks/{task_id}/tools/{tool}":{"post":{"tags":["Tools"],"summary":"Run a tool","description":"Run one tool on the task's current lead list.","operationId":"run_tool_tasks__task_id__tools__tool__post","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Id"}},{"name":"tool","in":"path","required":true,"schema":{"type":"string","title":"Tool"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Body"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/tasks/{task_id}/share":{"post":{"tags":["Results"],"summary":"Share a lead list","description":"Turn on a public link for the task's current lead list.","operationId":"share_tasks__task_id__share_post","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/account":{"get":{"tags":["Account"],"summary":"Account credits and limits","operationId":"get_account_account_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"Enrich":{"properties":{"emails":{"type":"boolean","title":"Emails","description":"True: find public emails on the websites of the leads. No credits.","default":false},"verify_emails":{"type":"boolean","title":"Verify Emails","description":"True: find emails, then check that they are deliverable. No credits.","default":false},"socials":{"type":"boolean","title":"Socials","description":"True: find LinkedIn, Instagram, Facebook, YouTube, X and TikTok profiles. No credits.","default":false},"phone_types":{"type":"boolean","title":"Phone Types","description":"True: find the line type of each phone: mobile, landline, toll-free or VoIP. No credits.","default":false}},"additionalProperties":false,"type":"object","title":"Enrich"},"FindLeadsInput":{"properties":{"categories":{"items":{"type":"string"},"type":"array","maxItems":5,"minItems":1,"title":"Categories","description":"Business categories to search, for example [\"dentist\", \"orthodontist\"]. One to five."},"locations":{"items":{"type":"string"},"type":"array","maxItems":10,"minItems":1,"title":"Locations","description":"Places to search, for example [\"Austin, TX\"]. One location, or one to ten with bulk_extraction=true."},"bulk_extraction":{"type":"boolean","title":"Bulk Extraction","description":"Search more than one location in this job. Only plans with bulk extraction have it.","default":false},"max_research_leads":{"type":"integer","maximum":5000,"minimum":1,"title":"Max Research Leads","description":"The credit limit. Each business researched costs one credit. The job never spends more."},"max_matching_leads":{"anyOf":[{"type":"integer","maximum":5000,"minimum":1},{"type":"null"}],"title":"Max Matching Leads","description":"The job stops when this number of leads meet every condition in match. Default: max_research_leads."},"enrich":{"$ref":"#/components/schemas/Enrich","description":"Contact steps to run. They do not use credits."},"checks":{"items":{"type":"string","enum":["website_status","website_security","website_technology","page_speed","ai_readability","conversion_paths","domain","digital_presence","budget_fit"]},"type":"array","maxItems":9,"title":"Checks","description":"Website and business checks to run. They do not use credits. website_status: is the site live, parked or dead. website_security: HTTPS and certificate. website_technology: platform, tools, booking, mobile score. page_speed: Google PageSpeed score, run on the final list only. ai_readability: can AI assistants read the site. conversion_paths: call, form, booking and quote on the homepage. domain: domain age, expiry, email provider. digital_presence: web and social presence segment. budget_fit: can the business pay for a service."},"match":{"anyOf":[{"$ref":"#/components/schemas/Match"},{"type":"null"}],"description":"Conditions a lead must meet to count as matching. A condition turns on the step it needs."},"rank_by":{"anyOf":[{"type":"string","enum":["digital_opportunity","quality","contactability"]},{"type":"null"}],"title":"Rank By","description":"Order of the final list. Default: search order."},"wait_seconds":{"type":"integer","maximum":45,"minimum":0,"title":"Wait Seconds","description":"Wait up to this number of seconds for the job to finish before the call returns.","default":20},"idempotency_key":{"anyOf":[{"type":"string","maxLength":128,"minLength":8},{"type":"null"}],"title":"Idempotency Key","description":"Use the same key on a retry to get the same task, not a second job."}},"additionalProperties":false,"type":"object","required":["categories","locations","max_research_leads"],"title":"FindLeadsInput"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Match":{"properties":{"has_website":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Website","description":"True: keep leads with a website. False: keep leads without one."},"has_email":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Email","description":"True: keep leads with an email. Turns on email finding."},"has_verified_email":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Verified Email","description":"True: keep leads with a deliverable email. Turns on email finding and verification."},"has_phone":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Phone","description":"True: keep leads with a phone number."},"has_social":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Social","description":"True: keep leads with a social profile. Turns on social profile finding."},"min_rating":{"anyOf":[{"type":"number","maximum":5,"minimum":0},{"type":"null"}],"title":"Min Rating","description":"Minimum Google rating, 0 to 5. A lead with no rating has 0."},"max_rating":{"anyOf":[{"type":"number","maximum":5,"minimum":0},{"type":"null"}],"title":"Max Rating","description":"Maximum Google rating, 0 to 5."},"min_reviews":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Min Reviews","description":"Minimum number of Google reviews. A lead with no reviews has 0."},"categories":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":20},{"type":"null"}],"title":"Categories","description":"Keep leads whose category contains one of these words."},"exclude_categories":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":20},{"type":"null"}],"title":"Exclude Categories","description":"Remove leads whose category contains one of these words."},"states":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":60},{"type":"null"}],"title":"States","description":"Two-letter US state codes, for example ['TX']. Removes leads in other states."},"website_statuses":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":20},{"type":"null"}],"title":"Website Statuses","description":"Keep leads whose website_status is in this list, for example ['live']. Turns on the website status check."},"website_platforms":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":20},{"type":"null"}],"title":"Website Platforms","description":"Keep leads on these website platforms, for example ['wordpress', 'wix']. Turns on the website technology check."}},"additionalProperties":false,"type":"object","title":"Match","description":"Conditions a lead must meet. Shared by find_leads and the filter_leads tool."},"QuestionView":{"properties":{"questions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Questions"}},"type":"object","required":["questions"],"title":"QuestionView"},"ReplyBody":{"properties":{"message":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Message"},"answers":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":20},{"type":"null"}],"title":"Answers"}},"type":"object","title":"ReplyBody"},"ResponseEnvelope_ResultsPage_":{"properties":{"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id"},"status":{"type":"string","title":"Status","default":"success"},"data":{"anyOf":[{"$ref":"#/components/schemas/ResultsPage"},{"type":"null"}]},"meta":{"additionalProperties":true,"type":"object","title":"Meta"},"error":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Error"}},"type":"object","title":"ResponseEnvelope[ResultsPage]"},"ResponseEnvelope_TaskView_":{"properties":{"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id"},"status":{"type":"string","title":"Status","default":"success"},"data":{"anyOf":[{"$ref":"#/components/schemas/TaskView"},{"type":"null"}]},"meta":{"additionalProperties":true,"type":"object","title":"Meta"},"error":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Error"}},"type":"object","title":"ResponseEnvelope[TaskView]"},"ResultsPage":{"properties":{"task_id":{"type":"string","title":"Task Id"},"rows":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Rows"},"total_count":{"type":"integer","title":"Total Count"},"matching_count":{"type":"integer","title":"Matching Count"},"returned_count":{"type":"integer","title":"Returned Count"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["task_id","rows","total_count","matching_count","returned_count","has_more","next_cursor"],"title":"ResultsPage"},"StepView":{"properties":{"name":{"type":"string","title":"Name"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"},"status":{"type":"string","title":"Status"},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary"},"rows":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rows"}},"type":"object","required":["name","status"],"title":"StepView"},"TaskInput":{"properties":{"prompt":{"type":"string","maxLength":4000,"minLength":3,"title":"Prompt","description":"What to find or do, in plain language. Example: \"Find 50 dentists in Austin, TX without a website and get their emails.\""},"max_leads":{"type":"integer","maximum":5000,"minimum":1,"title":"Max Leads","description":"Hard cap on lead credits this task may spend, including follow-up messages.","default":100},"idempotency_key":{"anyOf":[{"type":"string","maxLength":128,"minLength":8},{"type":"null"}],"title":"Idempotency Key","description":"Reuse on retry to get the same task instead of starting a second one."},"allow_questions":{"type":"boolean","title":"Allow Questions","description":"When true, LeadsAgent may pause with status needs_input to ask about an unclear job. When false, it never asks and makes reasonable assumptions instead.","default":true}},"additionalProperties":false,"type":"object","required":["prompt"],"title":"TaskInput"},"TaskView":{"properties":{"id":{"type":"string","title":"Id"},"kind":{"type":"string","enum":["agent","find_leads","search"],"title":"Kind","default":"agent"},"status":{"type":"string","enum":["queued","running","needs_input","completed","failed","cancelled"],"title":"Status"},"prompt":{"type":"string","title":"Prompt"},"source":{"type":"string","title":"Source"},"max_leads":{"type":"integer","title":"Max Leads"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"},"progress":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Progress"},"credits":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Credits"},"steps":{"items":{"$ref":"#/components/schemas/StepView"},"type":"array","title":"Steps"},"question":{"anyOf":[{"$ref":"#/components/schemas/QuestionView"},{"type":"null"}]},"reply":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reply"},"conversation":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Conversation"},"lead_count":{"type":"integer","title":"Lead Count","default":0},"results_ready":{"type":"boolean","title":"Results Ready","default":false},"lead_list":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Lead List"},"links":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Links"},"error":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Error"},"poll_after_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Poll After Seconds"},"next":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next"},"status_url":{"type":"string","title":"Status Url"}},"type":"object","required":["id","status","prompt","source","max_leads","created_at","status_url"],"title":"TaskView"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"APIKey":{"type":"apiKey","in":"header","name":"X-API-Key"},"Bearer":{"type":"http","scheme":"bearer"}}},"security":[{"APIKey":[]},{"Bearer":[]}]}