URL Shortify REST API Guide — Auth & Examples

This guide explains how to authenticate and use the URL Shortify REST API, with worked examples. For the full interactive endpoint reference — every path, parameter, and request/response schema generated from the OpenAPI spec — see the API Reference.

URL Shortify exposes a REST API so you can create and manage short links from external scripts, integrations, and automation instead of the WordPress admin. The API lives under the url-shortify/v1 namespace, is authenticated with API keys you generate in your site, and covers links and groups in the free version, with domains, tags, tracking pixels, UTM presets, auto-link keywords, and bulk creation in URL Shortify PRO.

Base URL

Every endpoint is served from the WordPress REST API on your own site, under the url-shortify/v1 namespace:

https://yoursite.com/wp-json/url-shortify/v1

Replace yoursite.com with your site's base URL (no trailing slash). All request and response bodies are JSON.

Authentication

The API authenticates with an API key — a Consumer Key and Consumer Secret pair. You can send them two ways; pick whichever fits your client.

Option A — Custom headers (recommended)

X-URL-SHORTIFY-CONSUMER-KEY: your_consumer_key
X-URL-SHORTIFY-CONSUMER-SECRET: your_consumer_secret

Option B — HTTP Basic Auth

Send the Consumer Key as the username and the Consumer Secret as the password:

Authorization: Basic base64(consumer_key:consumer_secret)

Generating an API key

API keys are managed from the plugin's Tools screen, not the Settings page:

1. Go to URL Shortify → Tools → REST API.
2. Click Add API Key.
3. Enter a Description (for example, "Content sync bot"), choose the User the key acts as, and set Permissions.
4. Save, then copy the Consumer Key and Consumer Secret. The secret is shown only once — store it in an environment variable or a secrets manager, never in source control.

Permissions control what the key can do:

Permission	Can do
Read	List and read links and groups (GET)
Write	Create, update, delete (POST, PUT, DELETE)
Read & Write	Both of the above

Pagination

List endpoints (GET /links, GET /groups, and the PRO collection endpoints) accept these query parameters:

Parameter	Default	Notes
page	1	Page of the collection to return.
per_page	20	Items per page. Maximum 100.

Responses include X-WP-Total and X-WP-TotalPages headers so you can page through large collections.

Free endpoints

These endpoints work in the free version of URL Shortify.

Links

Method	Path	Description
GET	/links	List short links (paginated), with group IDs, tag IDs, and the resolved short URL.
POST	/links	Create a short link. url is required; optional title, group_ids, tag_ids.
GET	/links/{id}	Get a single link by ID.
PUT	/links/{id}	Update a link.
DELETE	/links/{id}	Delete a link.

Groups

Method	Path	Description
GET	/groups	List link groups (paginated), including each group's link count.
POST	/groups	Create a group. name is required; optional description.
GET	/groups/{id}	Get a single group by ID.
PUT	/groups/{id}	Update a group.
DELETE	/groups/{id}	Delete a group.

Create a link

POST /links accepts the following body. Only url is required.

Field	Type	Required	Notes
url	string (URI)	yes	Destination URL to shorten. Must include the scheme (https://).
title	string	no	Human-readable name shown in the admin.
group_ids	integer[]	no	IDs of existing groups to assign the link to.
tag_ids	integer[]	no	IDs of existing tags to assign the link to (tags are a PRO feature).

curl -X POST 'https://yoursite.com/wp-json/url-shortify/v1/links' \
  -H 'Content-Type: application/json' \
  -H "X-URL-SHORTIFY-CONSUMER-KEY: $US_KEY" \
  -H "X-URL-SHORTIFY-CONSUMER-SECRET: $US_SECRET" \
  -d '{ "url": "https://example.com/my-long-url", "title": "My Link", "group_ids": [1] }'

A successful create returns HTTP 201 with success: true and the created link in data.

PRO endpoints

Bulk link creation

Method	Path	Description
POST	/links/bulk	Create many links in one request. Disabled by default — enable it under Settings → API → Bulk API.

The bulk endpoint has its own guide with the full payload, response, and batch-limit details: Bulk Generate Short Links via the API.

Domains, Tags, Tracking Pixels, UTM Presets & Auto Link Keywords

Each of these PRO resources exposes the same CRUD shape as links and groups — a collection endpoint (list + create) and an item endpoint (read, update, delete):

Resource	Collection	Item	Methods
Custom domains	/domains	/domains/{id}	GET, POST, PUT, DELETE
Tags	/tags	/tags/{id}	GET, POST, PUT, DELETE
Tracking pixels	/tracking-pixels	/tracking-pixels/{id}	GET, POST, PUT, DELETE
UTM presets	/utm-presets	/utm-presets/{id}	GET, POST, PUT, DELETE
Auto link keywords	/auto-link-keywords	/auto-link-keywords/{id}	GET, POST, PUT, DELETE

Response & error format

Successful responses return success: true and the payload in data. Errors use standard HTTP status codes:

Status	Meaning
200 / 201	Success (created for 201).
400	Bad request — a required field is missing or invalid.
401	Unauthorized — missing or invalid API key.
403	Forbidden — the key lacks permission, or the endpoint (e.g. Bulk API) is switched off.
500	Server error.

URL Shortify ships a machine-readable OpenAPI 3.0 description (openapi.json) in the plugin, which you can import into Postman, Insomnia, or a code generator to scaffold a client.

Conclusion

The URL Shortify REST API lets you manage links and groups programmatically in the free version and unlock bulk creation, domains, tags, tracking pixels, UTM presets, and auto-link keywords in PRO — all authenticated with an API key you generate under Tools → REST API. For high-volume creation, continue to Bulk Generate Short Links via the API.

FAQs

Is the URL Shortify REST API free?

The links and groups endpoints are available in the free version, so you can create, list, update, and delete short links and groups with a free API key. Advanced endpoints — bulk creation, custom domains, tags, tracking pixels, UTM presets, and auto-link keywords — require URL Shortify PRO. API keys themselves are generated in the free plugin under Tools → REST API.

Where do I create an API key?

Go to URL Shortify → Tools → REST API and click Add API Key. Give it a description, choose the user it acts as, and set its permissions to Read, Write, or Read & Write. After saving, copy the Consumer Key and Consumer Secret immediately — the secret is displayed only once and can't be retrieved later, so store it securely.

What is the API namespace and base URL?

All endpoints live under the url-shortify/v1 namespace on your own WordPress REST API, so the base URL is https://yoursite.com/wp-json/url-shortify/v1. Append a resource path such as /links or /groups to it. Because the API is served from your site, your links and click data never leave your infrastructure.

How many items can I request per page?

List endpoints default to 20 items per page and accept up to 100 via the per_page query parameter, alongside a page parameter. Responses include X-WP-Total and X-WP-TotalPages headers so you can loop through every page. To create many links at once instead of reading them, use the PRO bulk endpoint.

Why am I getting a 401 or 403 error?

A 401 means the API key is missing or invalid — check that both the Consumer Key and Secret are sent, either as the X-URL-SHORTIFY-CONSUMER-KEY/-SECRET headers or via HTTP Basic Auth. A 403 means the key lacks the required permission (for example, a Read key attempting a write) or the endpoint is disabled, as the Bulk API is until you enable it in Settings → API.