Skip to main content

Create, find, list or edit site-wide Outlinks links over REST

Premium Advanced Outlinks

These are the routes behind Settings → Site-wide Links and Guest Manager’s guest editor. They are install-wide, with no show in the path: every method needs manage_options (send an X-WP-Nonce for wp_rest from a browser) and Outlinks switched on for at least one show, else 403 benecaster_outlinks_not_active. While Outlinks is off for every show the routes do not exist at all (404 rest_no_route).

  • POST /benecaster-outlinks/v1/site-links with { url, slug? } answers with the link, as benecaster_outlinks_site_link() returns it: 201 with created: true when it was made, 200 with created: false when a site-wide link to that URL already existed. Errors match the function: 400 benecaster_outlinks_url_invalid (data.field is url), 400 benecaster_outlinks_slug_invalid and 409 benecaster_outlinks_slug_taken (with a free name in data.suggestion).
  • GET answers { go_base, items }, oldest first, site-wide links only. Each item has id, slug, go_url, destination_url, affiliate_url, expiry_date, expiry_fallback_url, geo_rules (each { country_code, destination_url, affiliate_url }), clicks, bot_clicks, last_clicked_at, last_clicked, status and http_status. clicks counts people only and bot_clicks the filtered ones. last_clicked_at is the last person’s click in ISO 8601 UTC (2026-11-02T10:30:00Z) and last_clicked the same moment in the site’s date and time formats; both are null when no person has clicked. status (healthy, broken, expired, unchecked or excluded) and http_status are Link Health’s.
  • PATCH …/site-links/{id} with any of destination_url, affiliate_url, expiry_date, expiry_fallback_url and geo_rules answers 200 with the item. The rules match a show’s tracked link: only the keys you send change, '' or null clears an optional one, geo_rules replaces the whole set, URLs must be http or https, and a bad field is 400 with data.field naming the first one. destination_url can be changed here because a site-wide link has no library item to follow; it cannot be cleared. An id that is not a site-wide link (unknown, or a show’s tracked link) is 404 benecaster_outlinks_redirect_not_found.

Code

<?php
$request = new WP_REST_Request( 'POST', '/benecaster-outlinks/v1/site-links' );
$request->set_body_params( [ 'url' => 'https://example.com/books/the-lean-startup', 'slug' => 'lean-startup-book' ] );
$response = rest_do_request( $request ); // As a user with manage_options.
$go_url   = $response->is_error() ? null : $response->get_data()['go_url'];

View on GitHub →

Need this built rather than just documented? See our services →