# Developer reference: REST API, webhooks & WP-CLI

*Collection: Displaying Libraries · Category: Developers · Availability: FileDeck Pro · Canonical URL: https://www.getfiledeck.com/docs/developer-api-reference/*

Everything a script, integration or agency build can hold onto. These
surfaces are stable: route shapes, webhook payloads and command names change
only with a major-version note in the changelog.


## JavaScript: starting a library added after page load

**Free, not Pro** — unlike the rest of this page.

FileDeck wires up every library once, when the page finishes loading. Anything
inserted afterwards — a page builder's tab or popup, an accordion, your own
script — misses that moment and would otherwise render perfectly and do nothing.

```js
window.filedeckInit();          // start every library that isn't running yet
window.filedeckInit( element ); // …or just the ones inside this element
```

Safe to call as often as you like: a library already running is left alone
(each one is stamped `data-fdk-ready`), so you cannot double-bind a control.

Each library fires a bubbling `fdk:ready` event as it starts, so you can hook
rather than poll:

```js
document.addEventListener( 'fdk:ready', function ( e ) {
	// e.target is the .filedeck element that just started
} );
```

The element has to be **in the document** when you call it. Append first, then
initialise.

## REST API

All under `/wp-json/`. Public routes respect the same access rules as the
library UI — a restricted document behaves identically everywhere.

| Route | Method | What it does |
|---|---|---|
| `wp/v2/filedeck_document` | GET | WordPress-native document listing (restricted documents excluded per visitor). Standard core parameters. |
| `filedeck/v1/library` | GET | One page of a library: server-rendered rows + JSON (see [headless front ends](https://www.getfiledeck.com/docs/headless-front-ends/) for the `ctx` token). |
| `filedeck/v1/download/<id>` | GET | The download route — counts, gates (terms/form/bot/lead/quotas) and access all enforced here. Signed variant carries `fdk_exp`/`fdk_sig`. |
| `filedeck/v1/zip` | POST | `{ ids: [..] }` → a zip of the permitted subset, gates applied per document. |
| `filedeck/v1/search` | POST | Content search (`{ q: "..." }`), page-jump hits included. |
| `filedeck/v1/semantic` | POST | Semantic search, `{ q: "..." }` (AI tier, when configured). |

## Webhooks

Three POST streams, all JSON, all opt-in under **Documents → Settings**:

- **Library events** — `document.published`, `.updated`, `.unpublished`,
  `.deleted`, `.downloaded`. Signed: verify `X-FileDeck-Signature` =
  `sha256=` + HMAC-SHA256 of `timestamp.body` with your signing secret. See
  [document events](https://www.getfiledeck.com/docs/document-events/) for payloads and a verifier.
- **Download notifications** — per-download payload (document, user,
  context).
- **Leads** — each captured lead (name, email, document).

## WP-CLI

```
wp filedeck status                 # counts, tier, available capabilities
wp filedeck list [--format=json] [--category=<slug>] [--per-page=<n>]
wp filedeck stats [--top=<n>] [--format=table|json|csv]   # documents by status, downloads, most downloaded
wp filedeck import <source>        # any one-click importer, headless (Pro)
wp filedeck import <file-or-folder>... [--category=<slug>] [--tags=a,b] [--status=draft] [--recursive] [--dry-run]   # files become documents (Pro)
wp filedeck protect <id>... --logged-in | --author | --users=<ids|logins|emails> | --clear   # a document's own access rule (Pro)
wp filedeck protect --category=<slug> --roles=editor,author | --clear   # a category's role rule (Pro)
wp filedeck share <id> [--expires=7d] [--once]   # print a signed, expiring download link (Pro)
wp filedeck reindex                # rebuild the content-search index (Pro)
wp filedeck event test --event=document.published --id=<id>   # webhook test (Pro)
```

`import` copies each file in through the same path as **Documents → Upload
Documents**, titles it from the file name, and moves it to protected storage when
its category is restricted; the original file stays where it was. `protect` does
what the document editor does, including moving the file and emailing people a
document is shared with. A link from `share` lets whoever holds it download the
document without signing in until it expires, so treat it like a password.

## The filters that matter

A curated set — every one is documented at its definition:

- `filedeck_download_allowed` — final allow/deny for any download; return
  `true` or a `WP_Error`. Every Pro gate uses this same filter.
- `filedeck_doc_row` — the assembled row before render/serialisation.
- `filedeck_library_data` — data attributes handed to the front-end script.
- `filedeck_formgate_hooks` — open the form gate from any form plugin's
  completion action.
- `filedeck_event` (action) — every library event, for PHP integrations.
- `filedeck_lead_captured` (action) — every captured lead.
- `filedeck_retention_applied` (action) — every retention action (AI tier).
- `filedeck_server_mode_threshold`, `filedeck_semantic_threshold`,
  `filedeck_zip_max_bytes`, `filedeck_max_upload_bytes` — the tuning knobs.

If you need a surface that isn't here, say so on the
[support page](https://www.getfiledeck.com/support/) — formalising another
route costs little once there's a real consumer for it.
