taskade · johnxie · Jun 19, 2026
diff --git a/Real API.json b/Real API.json
diff --git a/apis-living-system-development/api-v2-reference.md b/apis-living-system-development/api-v2-reference.md
@@ -9,7 +9,7 @@ description: >-
 The Public API **v2** is an **action-based** API: every operation is a `POST` to a named endpoint (`/listSpaces`, `/promptAgent`, `/createProject`), with a JSON body. It is not RESTful — there are no `GET /workspaces` or `PUT /tasks/{id}` style routes.
 
 {% hint style="info" %}
-**v2 is in beta and runs alongside v1.** v2 (`openapi 0.1.0`) is simpler and adds capabilities v1 lacks — most notably **`promptAgent`**. But v2 does **not** cover everything: tasks are **read-only** in v2, and there is no project-update endpoint. For full task CRUD (create/update/delete, assignees, dates, notes, fields) use the [REST API v1](comprehensive-api-guide/). See [Which API should I use?](#which-api-should-i-use) below.
+**v2 is in beta and runs alongside v1.** v2 is simpler and adds capabilities v1 lacks — most notably **`promptAgent`**. But v2 does **not** cover everything: tasks are **read-only** in v2, and there is no project-update endpoint. For full task CRUD (create/update/delete, assignees, dates, notes, fields) use the [REST API v1](comprehensive-api-guide/). See [Which API should I use?](#which-api-should-i-use) below.
 {% endhint %}
 
 The live OpenAPI spec is published at [taskade.com/api/documentation/v2](https://www.taskade.com/api/documentation/v2).

diff --git a/apis-living-system-development/developer-home.md b/apis-living-system-development/developer-home.md
@@ -109,6 +109,15 @@ Taskade ships **two** public HTTP APIs, both authenticated with the same token:
 | [REST API v1](comprehensive-api-guide/README.md) | `https://www.taskade.com/api/v1` | RESTful (`GET`/`POST`/`PUT`/`DELETE`) | Full task CRUD, assignees, dates, notes, fields |
 | [Action API v2](api-v2-reference.md) | `https://www.taskade.com/api/v2` | Action / RPC (`POST /{operation}`) | Prompting agents, agent lifecycle, bundles |
 
+{% hint style="info" %}
+**Live OpenAPI specs (source of truth)** — auto-generated from the running API, always current:
+
+* REST API v1 — [interactive docs](https://www.taskade.com/api/documentation/v1) · [openapi.json](https://www.taskade.com/api/documentation/v1/json)
+* Action API v2 — [interactive docs](https://www.taskade.com/api/documentation/v2) · [openapi.json](https://www.taskade.com/api/documentation/v2/json)
+
+The reference pages in this guide are hand-written companions (examples, patterns, best practices). When in doubt about an exact field or status code, the live spec wins.
+{% endhint %}
+
 Include your token in the `Authorization` header:
 
 ```bash
@@ -122,6 +131,16 @@ curl -X POST https://www.taskade.com/api/v2/listMyProjects \
      -H "Content-Type: application/json" -d '{}'
 ```
 
+## Errors
+
+Both APIs return a consistent JSON error envelope — expected failures come back as typed errors, not bare `500`s:
+
+```json
+{ "ok": false, "code": "PAYMENT_REQUIRED", "message": "Webhooks require a Pro plan or higher." }
+```
+
+The HTTP status matches the `code` (e.g. `401` `UNAUTHORIZED`, `402` `PAYMENT_REQUIRED`, `403` `FORBIDDEN`, `404` `NOT_FOUND`, `429` `TOO_MANY_REQUESTS`). Branch on `ok` and `code` rather than parsing `message`.
+
 ## What You Can Build
 
 - **Custom dashboards** that pull data from Taskade workspaces and projects

diff --git a/apis-living-system-development/webhooks.md b/apis-living-system-development/webhooks.md
@@ -14,8 +14,11 @@ Webhooks let your Taskade automations communicate with the outside world in both
 * **Outbound HTTP requests** — automations call _out_ to external APIs as action steps.
 * **Receiving Taskade events** — combine a Taskade **trigger** (e.g. _task completed_) with an outbound HTTP action to push events to your app.
 
-{% hint style="warning" %}
-There is **no** `POST /api/v2/webhooks` subscription endpoint and no event-subscription REST API. You receive Taskade events by **building an automation** with a Taskade trigger plus an HTTP action — see [Receiving Taskade Events](#receiving-taskade-events) below.
+{% hint style="info" %}
+Two ways to receive Taskade events:
+
+* **No-code:** build an automation with a Taskade trigger plus an HTTP action — see [Receiving Taskade Events](#receiving-taskade-events) below.
+* **Programmatic (Beta):** subscribe over the public API with `POST /api/v2/subscribeWebhook` — see [Programmatic Webhook Subscriptions](#programmatic-webhook-subscriptions-beta). Available on **Pro and above**.
 {% endhint %}
 
 ***
@@ -91,7 +94,7 @@ Content-Type: application/json
 Requests that omit or supply an incorrect token receive a `401 Unauthorized` response and are not processed.
 
 {% hint style="info" %}
-Check your plan's feature list at [taskade.com/pricing](https://www.taskade.com/pricing) for current availability of inbound webhook bearer token authentication.
+Webhook automations are available on **Pro and above**. Free and Starter plans cannot create webhook triggers or subscriptions. See [taskade.com/pricing](https://www.taskade.com/pricing).
 {% endhint %}
 
 ### Common Patterns
@@ -141,6 +144,48 @@ Response data from the HTTP request is available as dynamic variables in subsequ
 
 ***
 
+## Programmatic Webhook Subscriptions (Beta)
+
+{% hint style="info" %}
+Beta. Subscribing requires **Pro or above**. Subscriptions are account-level, and `task.due` is the only event wired end-to-end today — more events are rolling out. The authoritative schema is the live [Action API v2 spec](https://www.taskade.com/api/documentation/v2).
+{% endhint %}
+
+Subscribe to Taskade events over the public API without building an automation in the UI. This is the surface the official [Taskade integrations](https://github.com/taskade/integrations) (Zapier, n8n, Activepieces) build on.
+
+**Subscribe** — register a target URL for an event:
+
+```http
+POST https://www.taskade.com/api/v2/subscribeWebhook
+Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN
+Content-Type: application/json
+
+{
+  "targetUrl": "https://your-app.example.com/hooks/taskade",
+  "triggerType": "task.due"
+}
+```
+
+Returns `{ "ok": true, "hookId": "..." }`. Taskade then POSTs the event payload to `targetUrl` whenever a matching event fires. Delivery uses an SSRF-guarded fetch, so `targetUrl` **must be `https`**.
+
+**Unsubscribe** — remove a subscription by its `hookId`:
+
+```http
+POST https://www.taskade.com/api/v2/unsubscribeWebhook
+Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN
+Content-Type: application/json
+
+{ "hookId": "..." }
+```
+
+| Note | Detail |
+| --- | --- |
+| Plan | Subscribing requires **Pro or above** (otherwise `402 PAYMENT_REQUIRED`). Unsubscribing is always allowed, so a downgraded account can still clean up. |
+| Scope | Account-level — fires for matching events across your account. Per-project scope is planned. |
+| Events | `task.due` today. `task.assigned`, `task.completed`, `project.created` and more are rolling out. |
+| Limit | Up to 100 active subscriptions per account. |
+
+***
+
 ## Receiving Taskade Events
 
 To notify your app when something happens **in** Taskade (a task is added, a task is completed), build an automation that starts with a Taskade **trigger** and ends with an [Outbound HTTP Request](#outbound-http-requests) to your endpoint. The trigger's fields are available as dynamic variables in the HTTP body.

diff --git a/llms.txt b/llms.txt
@@ -52,10 +52,15 @@ Taskade lets teams collaborate on projects, create AI agents, automate workflows
 - [Developer Overview](apis-living-system-development/developers/README.md)
 - [Authentication](apis-living-system-development/developers/authentication.md)
 - [API Overview](apis-living-system-development/developers/api.md)
-- [Comprehensive API Guide](apis-living-system-development/comprehensive-api-guide/README.md)
+- [Comprehensive API Guide (REST v1)](apis-living-system-development/comprehensive-api-guide/README.md)
+- [Action API v2 Reference (Beta)](apis-living-system-development/api-v2-reference.md)
+- [TypeScript SDK Quickstart](apis-living-system-development/sdk-quickstart.md)
+- [Webhooks](apis-living-system-development/webhooks.md)
+- REST API v1 — live OpenAPI spec: https://www.taskade.com/api/documentation/v1 (JSON: https://www.taskade.com/api/documentation/v1/json)
+- Action API v2 (Beta) — live OpenAPI spec: https://www.taskade.com/api/documentation/v2 (JSON: https://www.taskade.com/api/documentation/v2/json)
 
 ## Links
 
 - [Taskade Website](https://taskade.com)
 - [Taskade Blog](https://www.taskade.com/blog)
-- [Taskade API](https://www.taskade.com/api/v1)
+- [Taskade API docs](https://www.taskade.com/api/documentation/v2)