API Reference
The reference below covers every endpoint in the Tasks API. Code examples are generated automatically; the live playground is disabled to prevent accidental writes to production from the docs site.
/api/v1/tasksAuthorization
BearerAuth Pass an API key issued from the agentlyleads workspace settings.
Example: Authorization: Bearer alk_live_xxxxxxxxxxxx
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/tasks" \ -H "Content-Type: application/json" \ -d '{ "tasks": [ { "title": "Discovery call with Acme", "type": "MEETING", "dueDate": "2026-09-10T14:00:00", "endAt": "2026-09-10T14:30:00", "contactExternalId": "hs_contact_123", "externalId": "booking_9F3K2" } ] }'{ "created": 1, "updated": 1, "errors": 0, "results": [ { "index": 0, "status": "created", "id": "018e2a4b-0000-7000-8000-aabbccddeeff" }, { "index": 1, "status": "updated", "id": "018e2a4b-1111-7000-8000-aabbccddeeff" } ]}{ "created": 1, "updated": 0, "errors": 1, "results": [ { "index": 0, "status": "created", "id": "018e2a4b-0000-7000-8000-aabbccddeeff" }, { "index": 1, "status": "error", "error": "contactExternalId: no contact found for \"NOPE\"." } ]}{ "error": "tasks must not be empty."}{ "error": "Invalid or missing API key."}{ "error": "API key missing required scope: write:tasks."}{ "error": "Rate limit exceeded."}/api/v1/tasksAuthorization
BearerAuth Pass an API key issued from the agentlyleads workspace settings.
Example: Authorization: Bearer alk_live_xxxxxxxxxxxx
In: header
Query Parameters
Filter to tasks linked to the contact with this external ID.
Filter to tasks linked to the lead with this external ID.
Filter to tasks linked to the deal with this external ID.
Filter to completed (true) or open (false) tasks.
Filter to tasks of this type.
Value in
- "TODO"
- "CALL"
- "EMAIL"
- "MEETING"
Only tasks updated at or after this ISO 8601 datetime.
date-timePage size.
1 <= value <= 1000100The nextCursor value from the previous page.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/tasks?contactExternalId=hs_contact_123&type=MEETING"{ "tasks": [ { "id": "cmq7task0alk34567890", "title": "Discovery call with Acme", "done": true, "dueDate": "2019-08-24T14:15:22Z", "allDay": true, "endAt": "2019-08-24T14:15:22Z", "description": "string", "type": "TODO", "priority": "LOW", "externalId": "booking_9F3K2", "contact": { "name": "Acme Corp", "externalId": "hs_company_42" }, "lead": { "name": "Acme Corp", "externalId": "hs_company_42" }, "deal": { "name": "Acme Corp", "externalId": "hs_company_42" }, "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z" } ], "nextCursor": "string"}{ "error": "type must be one of: TODO, CALL, EMAIL, MEETING."}{ "error": "Invalid or missing API key."}{ "error": "API key missing required scope: read:tasks."}{ "error": "Rate limit exceeded."}/api/v1/tasks/{id}Authorization
BearerAuth Pass an API key issued from the agentlyleads workspace settings.
Example: Authorization: Bearer alk_live_xxxxxxxxxxxx
In: header
Path Parameters
The agentlyleads task ID, or its externalId.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/api/v1/tasks/booking_9F3K2"{ "deleted": 1, "id": "cmq7task0alk34567890"}{ "error": "Invalid or missing API key."}{ "error": "API key missing required scope: write:tasks."}{ "error": "Task not found."}{ "error": "Rate limit exceeded."}