Split API docs into per-resource sections under docs/api/ (#2793)

* Split docs/API.md into per-resource sections under docs/api/ * Move API endpoints index above authentication in docs/api/README.md * Fix trailing comma in boards.md JSON example * Fix trailing comma in cards.md, add Response label to identity.md, add Rich Text to endpoint index
2026-04-06 14:00:17 -04:00
parent 00a5c6ef14
commit cdd13c1a61
17 changed files with 1803 additions and 1779 deletions
@@ -0,0 +1,117 @@
+# Webhooks
+
+Webhooks notify another application when something happens on a board. Only account admins can list, view, create, update, delete, or reactivate webhooks.
+
+## `GET /:account_slug/boards/:board_id/webhooks`
+
+Returns a paginated list of webhooks for a board.
+
+__Response:__
+
+```json
+[
+  {
+    "id": "03f5v9zkft4hj9qq0lsn9ohcm",
+    "name": "Production API",
+    "payload_url": "https://api.example.com/webhooks",
+    "active": true,
+    "signing_secret": "p94Bx2HjempCdYB4DTyZkY1b",
+    "subscribed_actions": ["card_published", "card_assigned", "card_closed"],
+    "created_at": "2025-12-05T19:36:35.534Z",
+    "url": "http://fizzy.localhost:3006/897362094/boards/03f5v9zkft4hj9qq0lsn9ohcy/webhooks/03f5v9zkft4hj9qq0lsn9ohcm",
+    "board": {
+      "id": "03f5v9zkft4hj9qq0lsn9ohcy",
+      "name": "Fizzy",
+      "all_access": true,
+      "created_at": "2025-12-05T19:36:35.534Z",
+      "url": "http://fizzy.localhost:3006/897362094/boards/03f5v9zkft4hj9qq0lsn9ohcy",
+      "creator": {
+        "id": "03f5v9zjw7pz8717a4no1h8a7",
+        "name": "David Heinemeier Hansson",
+        "role": "owner",
+        "active": true,
+        "email_address": "david@example.com",
+        "created_at": "2025-12-05T19:36:35.401Z",
+        "url": "http://fizzy.localhost:3006/897362094/users/03f5v9zjw7pz8717a4no1h8a7"
+      }
+    }
+  }
+]
+```
+
+## `GET /:account_slug/boards/:board_id/webhooks/:id`
+
+Returns a single webhook.
+
+__Response:__
+
+Returns the same webhook shape shown above.
+
+## `POST /:account_slug/boards/:board_id/webhooks`
+
+Creates a webhook.
+
+__Request:__
+
+```json
+{
+  "webhook": {
+    "name": "Production API",
+    "url": "https://api.example.com/webhooks",
+    "subscribed_actions": ["card_published", "card_assigned", "card_closed"]
+  }
+}
+```
+
+`subscribed_actions` accepts any of:
+`card_assigned`, `card_closed`, `card_postponed`, `card_auto_postponed`, `card_board_changed`, `card_published`, `card_reopened`, `card_sent_back_to_triage`, `card_triaged`, `card_unassigned`, `comment_created`
+
+__Response:__
+
+```
+HTTP/1.1 201 Created
+Location: http://fizzy.localhost:3006/897362094/boards/03f5v9zkft4hj9qq0lsn9ohcy/webhooks/03f5v9zkft4hj9qq0lsn9ohcm.json
+```
+
+Returns the created webhook in the response body.
+
+## `PATCH /:account_slug/boards/:board_id/webhooks/:id`
+
+Updates a webhook.
+
+__Request:__
+
+```json
+{
+  "webhook": {
+    "name": "Production API",
+    "subscribed_actions": ["card_closed"]
+  }
+}
+```
+
+The `url` is immutable after creation and is ignored on update.
+
+__Response:__
+
+Returns the updated webhook.
+
+## `DELETE /:account_slug/boards/:board_id/webhooks/:id`
+
+Deletes a webhook.
+
+__Response:__
+
+Returns `204 No Content` on success.
+
+## `POST /:account_slug/boards/:board_id/webhooks/:id/activation`
+
+Reactivates a deactivated webhook.
+
+__Response:__
+
+```
+HTTP/1.1 201 Created
+```
+
+Returns the reactivated webhook in the response body.