# API reference

All JSON responses use {request_id,status,data,meta}. Handled API errors add error.code, error.message and error.retryable. File exports return a file stream. The signed download route does not use an API key.

[Open the generated OpenAPI document](https://leadsagent.io/documentation/openapi.json)

- [POST /tasks](https://leadsagent.io/documentation/api/start-task): Give the agent a job in plain language. Set a hard lead-credit cap. Reuse the idempotency key only for the same request.
- [GET /tasks](https://leadsagent.io/documentation/api/list-tasks): List recent tasks owned by the authenticated account. Follow before to read older tasks.
- [GET /tasks/{id}](https://leadsagent.io/documentation/api/get-task): Read task status, progress, steps, questions, the agent reply, lead counts and result links.
- [POST /tasks/{id}/messages](https://leadsagent.io/documentation/api/reply-to-task): Answer a pending question or send a follow-up after the task finishes. Send answers or message.
- [POST /tasks/{id}/cancel](https://leadsagent.io/documentation/api/cancel-task): Ask a running task to stop. Read the task again to confirm its final status.
- [GET /tasks/{id}/results](https://leadsagent.io/documentation/api/task-results): Read one page of saved leads. Keep the filters and fields unchanged when you follow next_cursor.
- [GET /tasks/{id}/export](https://leadsagent.io/documentation/api/export-results): Download every saved lead for a task as CSV or JSON.
- [GET /downloads/{token}](https://leadsagent.io/documentation/api/download-results): Download the exact saved list version from a download_url returned by get-task.
- [POST /find](https://leadsagent.io/documentation/api/find-leads): Search categories and locations, then run only the checks and contact steps you request. Use start-task when the job needs judgment.
- [GET /tools](https://leadsagent.io/documentation/api/search-tools): Find tools that work on a task lead list. Search by action or exact tool name to get its input schema.
- [POST /tasks/{id}/tools/{tool}](https://leadsagent.io/documentation/api/run-tool): Run one catalog tool on the current task list. Call search-tools first, then use its exact tool name and arguments.
- [POST /tasks/{id}/share](https://leadsagent.io/documentation/api/share-results): Create a public link for the current lead list after the task finishes.
- [GET /account](https://leadsagent.io/documentation/api/account): Read account credits, reset time, request limits, key restrictions and permissions.

[All documentation](https://leadsagent.io/documentation/quickstart)
[OpenAPI](https://leadsagent.io/documentation/openapi.json)