API reference

Bring link management into your own workflows. Explore endpoints, review parameters, and use request and response examples to build your integration.

Complete operation reference

The OpenAPI specification includes tags, UTM templates, custom-domain management and provisioning, folder permissions, per-link analytics, and public help in addition to the examples below.

Method	Endpoint	Scope
GET	/links	links:read
POST	/links	links:write
GET	/links/{id}	links:read
PUT	/links/{id}	links:write
DELETE	/links/{id}	links:write
GET	/pages	pages:read
POST	/pages	pages:write
GET	/pages/{id}	pages:read
PUT	/pages/{id}	pages:write
DELETE	/pages/{id}	pages:write
POST	/pages/{id}/links	pages:write
PUT	/pages/{id}/links/{linkId}	pages:write
DELETE	/pages/{id}/links/{linkId}	pages:write
POST	/pages/{id}/plugins	pages:write
PUT	/pages/{id}/plugins/{pluginId}	pages:write
DELETE	/pages/{id}/plugins/{pluginId}	pages:write
POST	/pages/{id}/reorder	pages:write
GET	/analytics	analytics:read
GET	/qrcodes	qrcodes:read
POST	/qrcodes	qrcodes:write
GET	/qrcodes/{id}	qrcodes:read
PUT	/qrcodes/{id}	qrcodes:write
DELETE	/qrcodes/{id}	qrcodes:write
GET	/folders	folders:read
POST	/folders	folders:write
GET	/tags	tags:read
POST	/tags	tags:write
PUT	/tags/{id}	tags:write
DELETE	/tags/{id}	tags:write
GET	/utm-templates	utm:read
POST	/utm-templates	utm:write
PUT	/utm-templates/{id}	utm:write
DELETE	/utm-templates/{id}	utm:write
PUT	/folders/{id}	folders:write
DELETE	/folders/{id}	folders:write
GET	/folders/{id}/permissions	folders:read
GET	/folders/{id}/permissions/me	folders:read
PUT	/folders/{id}/permissions/{userId}	folders:write
GET	/domains	domains:read
POST	/domains	domains:write
GET	/domains/{id}	domains:read
PUT	/domains/{id}	domains:write
DELETE	/domains/{id}	domains:write
POST	/domains/{id}/verify	domains:write
POST	/domains/{id}/retry-ssl	domains:write
GET	/links/{id}/clicks	links:read
GET	/links/{id}/analytics	links:read
POST	/links/fetch-meta	links:write
GET	/analytics/options	analytics:read
GET	/help/search	Public documentation
GET	/help/{slug}	Public documentation

Introduction

The Goose.re REST API organizes endpoints by resource, including links, bio pages, QR codes, and folders. Send request bodies as JSON with Content-Type: application/json, and use the JSON responses and HTTP status codes to handle results. Form-encoded bodies are also supported for POST requests; use JSON for PUT requests. Each endpoint below lists its parameters and example data; an asterisk marks a required parameter. Response examples show representative fields; additional fields may be returned. The OpenAPI specification lists further optional fields.

Base URL


                        https://goose.re/api/v1

Authentication

Team owners and admins can create and manage API keys in Team Settings → API Keys. Copy the full key when it is created; it is shown only once. Keys use the prefix goose_ followed by 48 hexadecimal characters.

Set GOOSE_API_KEY to your full key, then include it in the Authorization header as a bearer token on each request. The key selects its workspace; X-Team-Id does not switch the workspace for an API key. Grant the required read or write scope for each resource. Write scopes do not include read access. Revoked, expired, or IP-restricted keys fail authentication.

Example request

curl https://goose.re/api/v1/links \
  -H "Authorization: Bearer ${GOOSE_API_KEY}"

Responses & errors

Successful responses contain success: true, message, and data. Deletions and reordering return data: null. Link lists use data.links and data.total; QR code lists use data.qrcodes and data.total. Page and folder lists return arrays in data.

Use limit (default 50, maximum 100) and offset (default 0) for link and QR code lists. Page and folder lists are not paginated. Database timestamps generally use YYYY-MM-DD HH:MM:SS, without a timezone offset; do not assume ISO 8601 or a trailing Z.

Errors contain success: false and message, with an optional errors object mapping field names to arrays of messages. HTTP 200 indicates success; 201 indicates creation; 400 indicates invalid input; 401 indicates failed authentication; 403 indicates missing scope or permissions; 404 indicates a missing resource; and 422 indicates validation or business-rule failure.

If a request receives HTTP 429, back off before retrying and honor any retry or rate-limit headers provided. No fixed requests-per-minute quota is specified here.

Links

POST /api/v1/links

Create a short link

Create a short link for a destination URL. Optionally choose a recognizable slug, use a custom domain, and assign the link to a folder.

Required API key scope: links:write

Parameters

Parameter	Location	Type	Description
url *	body	string	The full URL visitors should reach when they open the short link.
custom_slug	body	string	Optional short code: 3–20 letters, numbers, underscores, or hyphens, starting with a letter or number. Must be unique within the selected domain. Omit to generate a code.
domain_id	body	string (UUID)	The ID of the custom domain to use.
folder_id	body	string (UUID)	The ID of the folder for the short link.
title	body	string	An internal label that helps you identify the link in your dashboard.
redirect_type	body	string	screen, instant, or password. Password redirects also require password. Default: `screen`
password	body	string	Required when redirect_type is password.

Example request body

{
    "url": "https://example.com/very-long-url-path-here",
    "custom_slug": "my-promo",
    "folder_id": "9a60e0a5-2962-4217-ba5c-0b92db2c92be",
    "title": "Summer Promo Link"
}

Example response (HTTP 201)

{
    "success": true,
    "message": "Link created",
    "data": {
        "id": "3f381c81-8178-4ef8-a532-3532f7a9d0a6",
        "destination_url": "https://example.com/very-long-url-path-here",
        "short_url": "https://goose.re/my-promo",
        "domain_id": null,
        "folder_id": "9a60e0a5-2962-4217-ba5c-0b92db2c92be",
        "title": "Summer Promo Link",
        "is_active": 1,
        "created_at": "2026-07-04 22:19:50",
        "short_code": "my-promo",
        "total_clicks": 0
    }
}

GET /api/v1/links

List short links

Retrieve short links in the authenticated team workspace. Use pagination to work through results and search to find specific links.

Required API key scope: links:read

Parameters

Parameter	Location	Type	Description
limit	query	integer	Number of results to return, from 1 to 100. Default: `50`
offset	query	integer	The number of results to skip before returning this page. Default: `0`
search	query	string	A search term to filter links by title, slug, or destination URL.
is_active	query	integer	Filter by active state: 0 or 1.
folder_id	query	string (UUID)	Filter by folder ID; an empty string applies no folder filter.
sort_by	query	string	created_at, short_url, or total_clicks. Default: `created_at`
sort_order	query	string	asc or desc. Default: `desc`

Example response (HTTP 200)

{
    "success": true,
    "message": "OK",
    "data": {
        "links": [
            {
                "id": "3f381c81-8178-4ef8-a532-3532f7a9d0a6",
                "destination_url": "https://example.com/very-long-url-path-here",
                "short_url": "https://goose.re/my-promo",
                "created_at": "2026-07-01 12:00:00",
                "short_code": "my-promo",
                "total_clicks": 241
            },
            {
                "id": "db0e2b9c-7e61-4682-8280-998818dbcfb4",
                "destination_url": "https://google.com",
                "short_url": "https://goose.re/search",
                "created_at": "2026-07-02 15:30:00",
                "short_code": "search",
                "total_clicks": 89
            }
        ],
        "total": 2
    }
}

GET /api/v1/links/{id}

Retrieve a short link

Retrieve the destination, public URL, and configuration of a specific short link by its ID.

Required API key scope: links:read

Parameters

Parameter	Location	Type	Description
id *	path	string (Path Parameter)	The unique identifier of the link.

Example response (HTTP 200)

{
    "success": true,
    "message": "OK",
    "data": {
        "id": "3f381c81-8178-4ef8-a532-3532f7a9d0a6",
        "destination_url": "https://example.com/very-long-url-path-here",
        "short_url": "https://goose.re/my-promo",
        "domain_id": null,
        "folder_id": "9a60e0a5-2962-4217-ba5c-0b92db2c92be",
        "title": "Summer Promo Link",
        "is_active": 1,
        "created_at": "2026-07-01 12:00:00",
        "short_code": "my-promo",
        "total_clicks": 241
    }
}

PUT /api/v1/links/{id}

Update a short link

Change the destination or title of an existing short link. Include the properties you want to update.

Required API key scope: links:write

Parameters

Parameter	Location	Type	Description
id *	path	string (Path Parameter)	The unique identifier of the link to update.
destination_url	body	string	The new destination URL.
title	body	string	The updated link title.
is_active	body	integer	1 to enable the link, 0 to archive it.
folder_id	body	string (UUID) or null	Move the link to a folder, or use null to remove it from its folder.

Example request body

{
    "title": "Updated Campaign URL",
    "destination_url": "https://new-destination.com/page"
}

Example response (HTTP 200)

{
    "success": true,
    "message": "Link updated",
    "data": {
        "id": "3f381c81-8178-4ef8-a532-3532f7a9d0a6",
        "destination_url": "https://new-destination.com/page",
        "short_url": "https://goose.re/my-promo",
        "title": "Updated Campaign URL",
        "is_active": 1,
        "created_at": "2026-07-01 12:00:00",
        "short_code": "my-promo",
        "total_clicks": 241
    }
}

DELETE /api/v1/links/{id}

Delete a short link

Permanently remove a short link. The short URL will no longer direct visitors to its destination.

Required API key scope: links:write

Parameters

Parameter	Location	Type	Description
id *	path	string (Path Parameter)	The unique identifier of the link to delete.

Example response (HTTP 200)

{
    "success": true,
    "message": "Link deleted",
    "data": null
}

Bio pages

GET /api/v1/pages

List bio pages

Retrieve bio pages in the authenticated team workspace. Filter by folder and choose a sort order to organize the results.

Required API key scope: pages:read

Parameters

Parameter	Location	Type	Description
folder_id	query	string (UUID)	Filter by folder ID. Pass an empty string to return pages without a folder.
sort_by	query	string	Sort field: `created_at`, `title`, `slug`, or `total_clicks`.
sort_order	query	string	Sort direction: `asc` or `desc`.

Example response (HTTP 200)

{
    "success": true,
    "message": "OK",
    "data": [
        {
            "id": "7e9c8172-e612-4a0b-9c71-00829db7120a",
            "slug": "creative-team",
            "title": "Design & Creative Team Hub",
            "folder_id": "9a60e0a5-2962-4217-ba5c-0b92db2c92be",
            "folder_name": "Marketing Campaigns",
            "link_count": 5,
            "plugin_count": 2,
            "created_at": "2026-06-15 09:45:00",
            "total_clicks": 512
        }
    ]
}

POST /api/v1/pages

Create a bio page

Create a bio page in your team workspace with a public URL, page title, and optional brand styling.

Required API key scope: pages:write

Parameters

Parameter	Location	Type	Description
slug *	body	string	The unique slug for the public page URL.
title *	body	string	The title displayed at the top of the bio page.
description	body	string	A brief description or subtitle for the bio page.
theme	body	string	Theme ID: default, executive, editorial, onyx, sunset, glassmorphism, terminal, or forest. Unknown values fall back to default.
theme_accent_1	body	string (Hex Color)	The primary brand color as a hexadecimal string, such as `#ff0055`.
theme_accent_2	body	string (Hex Color)	The secondary brand or accent color as a hexadecimal string.
domain_id	body	string (UUID)	The ID of the custom domain configuration.
folder_id	body	string (UUID)	The ID of the folder for the bio page.

Example request body

{
    "slug": "developer-advocacy",
    "title": "Developer Relations Resources",
    "description": "Find all official Goose.re developer templates, toolkits, and client SDKs.",
    "theme": "glassmorphism",
    "theme_accent_1": "#6366f1"
}

Example response (HTTP 201)

{
    "success": true,
    "message": "Bio Page created successfully",
    "data": {
        "id": "cf067c29-37ea-4bf0-b6c8-52c67cfc0a21",
        "team_id": "1f2a3b4c-5d6e-4789-8abc-1234567890ab",
        "slug": "developer-advocacy",
        "title": "Developer Relations Resources",
        "description": "Find all official Goose.re developer templates, toolkits, and client SDKs.",
        "theme": "glassmorphism",
        "theme_accent_1": "#6366f1",
        "folder_id": null,
        "domain_id": null,
        "theme_accent_2": null
    }
}

GET /api/v1/pages/{id}

Retrieve a bio page

Retrieve a bio page and its layout, including link buttons and the configuration of its active widgets.

Required API key scope: pages:read

Parameters

Parameter	Location	Type	Description
id *	path	string (Path Parameter)	The unique ID of the bio page.

Example response (HTTP 200)

{
    "success": true,
    "message": "OK",
    "data": {
        "id": "cf067c29-37ea-4bf0-b6c8-52c67cfc0a21",
        "slug": "developer-advocacy",
        "title": "Developer Relations Resources",
        "links": [
            {
                "id": "a903f581-2ed1-4aca-8a25-92be330bdc01",
                "label": "GitHub Org",
                "url": "https://github.com/goose-re",
                "icon": "fa-github",
                "color": "#ffffff",
                "bg_color": "#24292e",
                "animation": "bounce",
                "sort_order": 1
            }
        ],
        "plugins": [
            {
                "id": "c679ed12-5231-4ba9-a3cc-743aa0ad72e2",
                "type": "gallery",
                "config": {
                    "title": "Selected work",
                    "layout": "carousel",
                    "images": [
                        {
                            "url": "/uploads/images/project.webp",
                            "alt": "Product detail"
                        }
                    ]
                },
                "sort_order": 2,
                "is_supported": true,
                "is_valid": true
            }
        ]
    }
}

PUT /api/v1/pages/{id}

Update a bio page

Update the content and appearance of a bio page, including its title, description, theme, images, and custom CSS.

Required API key scope: pages:write

Parameters

Parameter	Location	Type	Description
id *	path	string (Path Parameter)	The unique ID of the bio page to update.
slug	body	string	The new URL slug.
title	body	string	The updated page title.
description	body	string	The subtitle text for the bio page.
profile_image	body	string (URL)	The URL of the profile image.
background_image	body	string (URL)	The URL of the background image.
favicon	body	string (URL)	The URL of the custom favicon.
theme	body	string	The active preset theme.
theme_accent_1	body	string (Hex)	The primary brand color for the theme.
theme_accent_2	body	string (Hex)	The secondary brand color for the theme.
custom_css	body	string	Custom CSS overrides added to the bio page template.
folder_id	body	string (UUID) or null	Folder ID, or null to remove the folder.
domain_id	body	string (UUID) or null	Custom domain ID, or null to remove the custom domain.

Example request body

{
    "title": "Updated Developer Hub",
    "theme_accent_1": "#4f46e5",
    "custom_css": ".bio-btn { border-radius: 4px; }"
}

Example response (HTTP 200)

{
    "success": true,
    "message": "Bio Page updated successfully",
    "data": {
        "id": "cf067c29-37ea-4bf0-b6c8-52c67cfc0a21",
        "slug": "developer-advocacy",
        "title": "Updated Developer Hub",
        "theme_accent_1": "#4f46e5",
        "custom_css": ".bio-btn { border-radius: 4px; }",
        "created_at": "2026-07-04 22:19:50"
    }
}

DELETE /api/v1/pages/{id}

Delete a bio page

Permanently remove a bio page, including its link buttons and widgets. Its public page will no longer be available.

Required API key scope: pages:write

Parameters

Parameter	Location	Type	Description
id *	path	string (Path Parameter)	The unique ID of the bio page to delete.

Example response (HTTP 200)

{
    "success": true,
    "message": "Bio Page deleted successfully",
    "data": null
}

POST /api/v1/pages/{id}/links

Add a bio page link

Add a link button to a bio page with a label and destination URL. Optionally customize its icon, colors, animation, and position.

Required API key scope: pages:write

Parameters

Parameter	Location	Type	Description
id *	path	string (Path Parameter)	The ID of the bio page.
label *	body	string	The text displayed on the link button.
url *	body	string (URL)	The destination URL for the link button.
icon	body	string	The Font Awesome icon class.
color	body	string (Hex) or null	Use #RRGGBB, or null/empty string to clear the override. Invalid formats return HTTP 400.
bg_color	body	string (Hex) or null	Use #RRGGBB, or null/empty string to clear the override. Invalid formats return HTTP 400.
animation	body	string	The entrance or loop animation, such as `bounce` or `none`.
sort_order	body	integer	The position of the link in the page layout.

Example request body

{
    "label": "Official Documentation",
    "url": "https://goose.re/docs",
    "icon": "fa-book-open",
    "bg_color": "#4f46e5",
    "color": "#ffffff"
}

Example response (HTTP 201)

{
    "success": true,
    "message": "Link added successfully",
    "data": {
        "id": "a903f581-2ed1-4aca-8a25-92be330bdc01",
        "page_id": "cf067c29-37ea-4bf0-b6c8-52c67cfc0a21",
        "label": "Official Documentation",
        "url": "https://goose.re/docs",
        "icon": "fa-book-open",
        "bg_color": "#4f46e5",
        "color": "#ffffff",
        "sort_order": 0,
        "animation": "none"
    }
}

PUT /api/v1/pages/{id}/links/{linkId}

Update a bio page link

Update an existing bio page link button, including its label, destination, icon, and appearance.

Required API key scope: pages:write

Parameters

Parameter	Location	Type	Description
id *	path	string (Path Parameter)	The ID of the bio page.
linkId *	path	string (Path Parameter)	The ID of the link element.
label	body	string	The updated button label.
url	body	string (URL)	The updated destination URL.
icon	body	string	The Font Awesome icon name.
color	body	string (Hex) or null	Use #RRGGBB, or null/empty string to clear the override. Invalid formats return HTTP 400.
bg_color	body	string (Hex) or null	Use #RRGGBB, or null/empty string to clear the override. Invalid formats return HTTP 400.
animation	body	string	The hover or attention animation.
sort_order	body	integer	Position in the page layout.

Example request body

{
    "label": "Developer Hub & Docs",
    "bg_color": "#312e81"
}

Example response (HTTP 200)

{
    "success": true,
    "message": "Link updated successfully",
    "data": {
        "id": "a903f581-2ed1-4aca-8a25-92be330bdc01",
        "page_id": "cf067c29-37ea-4bf0-b6c8-52c67cfc0a21",
        "label": "Developer Hub & Docs",
        "url": "https://goose.re/docs",
        "icon": "fa-book-open",
        "bg_color": "#312e81",
        "color": "#ffffff",
        "sort_order": 0,
        "animation": "none"
    }
}

DELETE /api/v1/pages/{id}/links/{linkId}

Delete a bio page link

Remove a specific link button from a bio page while keeping the rest of the page in place.

Required API key scope: pages:write

Parameters

Parameter	Location	Type	Description
id *	path	string (Path Parameter)	The ID of the bio page.
linkId *	path	string (Path Parameter)	The ID of the link to delete.

Example response (HTTP 200)

{
    "success": true,
    "message": "Link deleted successfully",
    "data": null
}

POST /api/v1/pages/{id}/plugins

Add a bio page widget

Add a content widget to a bio page. Choose a supported widget type and supply its configuration; the widget uses the page theme.

Required API key scope: pages:write

Parameters

Parameter	Location	Type	Description
id *	path	string (Path Parameter)	The ID of the bio page.
type *	body	string	One of `spotlight`, `socials`, `text_block`, `youtube`, `gallery`, `countdown`, or `faq`.
config	body	object	Configuration object for the widget type. On update this replaces the previous configuration; omitted configuration is retained. Invalid configurations return HTTP 422.
sort_order	body	integer	The position of the widget in the page layout.

Example request body

{
    "type": "socials",
    "config": {
        "twitter": "https://twitter.com/goose_re",
        "linkedin": "https://linkedin.com/company/goose-re"
    }
}

Example response (HTTP 201)

{
    "success": true,
    "message": "Widget added successfully",
    "data": {
        "id": "c679ed12-5231-4ba9-a3cc-743aa0ad72e2",
        "page_id": "cf067c29-37ea-4bf0-b6c8-52c67cfc0a21",
        "type": "socials",
        "config": {
            "title": "Find me online",
            "display": "labels",
            "twitter": "https://twitter.com/goose_re",
            "linkedin": "https://linkedin.com/company/goose-re",
            "instagram": "",
            "youtube": "",
            "tiktok": "",
            "github": ""
        },
        "sort_order": 1,
        "is_supported": true,
        "is_valid": true
    }
}

PUT /api/v1/pages/{id}/plugins/{pluginId}

Update a bio page widget

Replace the configuration of an existing bio page widget and optionally update its position in the layout.

Required API key scope: pages:write

Parameters

Parameter	Location	Type	Description
id *	path	string (Path Parameter)	The ID of the bio page.
pluginId *	path	string (Path Parameter)	The ID of the widget to update.
config	body	object	Configuration object for the widget type. On update this replaces the previous configuration; omitted configuration is retained. Invalid configurations return HTTP 422.
sort_order	body	integer	The position of the widget in the page layout.

Example request body

{
    "config": {
        "twitter": "https://twitter.com/goose_re_updates",
        "linkedin": "https://linkedin.com/company/goose-re"
    }
}

Example response (HTTP 200)

{
    "success": true,
    "message": "Widget updated successfully",
    "data": {
        "id": "c679ed12-5231-4ba9-a3cc-743aa0ad72e2",
        "page_id": "cf067c29-37ea-4bf0-b6c8-52c67cfc0a21",
        "type": "socials",
        "config": {
            "title": "Find me online",
            "display": "labels",
            "twitter": "https://twitter.com/goose_re_updates",
            "linkedin": "https://linkedin.com/company/goose-re",
            "instagram": "",
            "youtube": "",
            "tiktok": "",
            "github": ""
        },
        "sort_order": 1,
        "is_supported": true,
        "is_valid": true
    }
}

DELETE /api/v1/pages/{id}/plugins/{pluginId}

Delete a bio page widget

Remove a specific widget from a bio page while keeping its other content in place.

Required API key scope: pages:write

Parameters

Parameter	Location	Type	Description
id *	path	string (Path Parameter)	The ID of the bio page.
pluginId *	path	string (Path Parameter)	The ID of the widget to delete.

Example response (HTTP 200)

{
    "success": true,
    "message": "Widget deleted successfully",
    "data": null
}

POST /api/v1/pages/{id}/reorder

Reorder page content

Set the display order of link buttons and widgets in one request by supplying their IDs, types, and positions.

Required API key scope: pages:write

Parameters

Parameter	Location	Type	Description
id *	path	string (Path Parameter)	The ID of the bio page.
items	body	array of objects	The page items to reorder. Each item must include `id` (UUID), `type` (`link` or `plugin`), and `sort_order` (integer). Default: `[]`

Example request body

{
    "items": [
        {
            "id": "a903f581-2ed1-4aca-8a25-92be330bdc01",
            "type": "link",
            "sort_order": 1
        },
        {
            "id": "c679ed12-5231-4ba9-a3cc-743aa0ad72e2",
            "type": "plugin",
            "sort_order": 2
        }
    ]
}

Example response (HTTP 200)

{
    "success": true,
    "message": "Order saved successfully",
    "data": null
}

Analytics

GET /api/v1/analytics

Retrieve analytics

Retrieve aggregated click analytics for the authenticated team workspace to review traffic trends and audience breakdowns.

Required API key scope: analytics:read

Parameters

Parameter	Location	Type	Description
period	query	string	24h, 7d, 30d, 90d, or all. The 24h period groups by hour; other periods group by day. Default: `30d`
link_id	query	string (UUID)	Filter clicks for one short link.
folder_id	query	string (UUID)	Filter by folder.
tag_id	query	string (UUID)	Filter links by tag.
builder	query	string (JSON array)	URL-encoded JSON array of filters with field, operator (is or is_not), and values. Fields: link, page, folder, language, subnet, device, browser, os, tag.

Example response (HTTP 200)

{
    "success": true,
    "message": "OK",
    "data": {
        "timeSeries": [
            {
                "date": "2026-07-01",
                "count": 450
            },
            {
                "date": "2026-07-02",
                "count": 510
            },
            {
                "date": "2026-07-03",
                "count": 580
            }
        ],
        "browsers": [],
        "os": [],
        "devices": [
            {
                "name": "desktop",
                "count": 920
            },
            {
                "name": "mobile",
                "count": 540
            },
            {
                "name": "tablet",
                "count": 80
            }
        ],
        "languages": [],
        "subnets": [],
        "referrers": [],
        "topLinks": [],
        "topDestinations": [],
        "utm": {
            "source": [],
            "medium": [],
            "campaign": [],
            "term": [],
            "content": []
        },
        "recentClicks": [],
        "stats": {
            "total_clicks": 1540,
            "unique_visitors": 1200,
            "avg_clicks": 1.3,
            "top_referrer": "Direct / None"
        }
    }
}

QR codes

GET /api/v1/qrcodes

List QR codes

Retrieve QR codes in the authenticated team workspace. Use search, folder filters, sorting, and pagination to find the codes you need.

Required API key scope: qrcodes:read

Parameters

Parameter	Location	Type	Description
search	query	string	Filter QR codes by name, short code, or destination URL.
folder_id	query	string (UUID)	Filter by folder ID; an empty string applies no folder filter.
sort_by	query	string	Sort field: created_at, name, or total_clicks. The legacy short_url value also sorts by name.
sort_order	query	string	Sort direction: `asc` or `desc`.
limit	query	integer	Number of results to return, from 1 to 100. Default: `50`
offset	query	integer	The number of results to skip before returning this page. Default: `0`

Example response (HTTP 200)

{
    "success": true,
    "message": "OK",
    "data": {
        "qrcodes": [
            {
                "id": "f13b09e1-3a44-4eab-bf01-20a7b672ab51",
                "team_id": "1f2a3b4c-5d6e-4789-8abc-1234567890ab",
                "link_id": "3f381c81-8178-4ef8-a532-3532f7a9d0a6",
                "folder_id": "9a60e0a5-2962-4217-ba5c-0b92db2c92be",
                "name": "Flyer QR Campaign",
                "design_config": {
                    "dotsOptions": {
                        "type": "rounded",
                        "color": "#000000"
                    },
                    "backgroundOptions": {
                        "color": "#ffffff"
                    }
                },
                "short_url": "https://goose.re/my-promo",
                "folder_name": "Marketing Campaigns",
                "created_at": "2026-07-04 12:00:00",
                "updated_at": "2026-07-04 12:00:00"
            }
        ],
        "total": 1
    }
}

POST /api/v1/qrcodes

Create a QR code

Create a QR code. Supply at least one of link_id or url; link_id takes precedence. A URL creates a short link automatically. The folder is inherited from the linked short link when available, or defaults to a QR Codes folder for automatically created links.

Required API key scope: qrcodes:write

Parameters

Parameter	Location	Type	Description
name *	body	string	A descriptive name to identify the QR code in your workspace.
design_config *	body	object / JSON string	QR Code Styling options stored as an object or JSON string, such as dotsOptions and backgroundOptions. Rendering the QR image is handled by the client.
url	body	string	The destination URL. If provided when link_id is empty, a new short link is created automatically.
link_id	body	string (UUID)	The ID of an existing short link to connect to the QR code.
folder_id	body	string (UUID)	The ID of the folder for the QR code.

Example request body

{
    "name": "Event Banner QR",
    "design_config": {
        "dotsOptions": {
            "type": "rounded",
            "color": "#1d4ed8"
        },
        "backgroundOptions": {
            "color": "#ffffff"
        }
    },
    "url": "https://example.com/event-registration"
}

Example response (HTTP 201)

{
    "success": true,
    "message": "QR Code created",
    "data": {
        "id": "5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d",
        "team_id": "1f2a3b4c-5d6e-4789-8abc-1234567890ab",
        "link_id": "8e9f0a1b-2c3d-4e5f-6a7b-8c9d0e1f2a3b",
        "folder_id": "9a60e0a5-2962-4217-ba5c-0b92db2c92be",
        "name": "Event Banner QR",
        "design_config": {
            "dotsOptions": {
                "type": "rounded",
                "color": "#1d4ed8"
            },
            "backgroundOptions": {
                "color": "#ffffff"
            }
        },
        "short_url": "https://goose.re/event-promo",
        "created_at": "2026-07-04 22:26:10",
        "updated_at": "2026-07-04 22:26:10"
    }
}

GET /api/v1/qrcodes/{id}

Retrieve a QR code

Retrieve the design settings, connected short link, and folder details of a specific QR code by its ID.

Required API key scope: qrcodes:read

Parameters

Parameter	Location	Type	Description
id *	path	string (Path Parameter)	The unique identifier of the QR code.

Example response (HTTP 200)

{
    "success": true,
    "message": "OK",
    "data": {
        "id": "5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d",
        "team_id": "1f2a3b4c-5d6e-4789-8abc-1234567890ab",
        "link_id": "8e9f0a1b-2c3d-4e5f-6a7b-8c9d0e1f2a3b",
        "folder_id": "9a60e0a5-2962-4217-ba5c-0b92db2c92be",
        "name": "Event Banner QR",
        "design_config": {
            "dotsOptions": {
                "type": "rounded",
                "color": "#1d4ed8"
            },
            "backgroundOptions": {
                "color": "#ffffff"
            }
        },
        "short_url": "https://goose.re/event-promo",
        "created_at": "2026-07-04 22:26:10",
        "updated_at": "2026-07-04 22:26:10"
    }
}

PUT /api/v1/qrcodes/{id}

Update a QR code

Update an existing QR code by changing its name, design settings, connected short link, or folder.

Required API key scope: qrcodes:write

Parameters

Parameter	Location	Type	Description
id *	path	string (Path Parameter)	The unique identifier of the QR code to update.
name	body	string	The updated name of the QR code.
design_config	body	object / JSON string	QR Code Styling options stored as an object or JSON string, such as dotsOptions and backgroundOptions. Rendering the QR image is handled by the client.
link_id	body	string (UUID)	The ID of the short link to connect to the QR code.
folder_id	body	string (UUID)	The ID of the folder for the QR code.

Example request body

{
    "name": "Updated Event Banner QR",
    "design_config": {
        "dotsOptions": {
            "type": "rounded",
            "color": "#000000"
        },
        "backgroundOptions": {
            "color": "#f3f4f6"
        }
    }
}

Example response (HTTP 200)

{
    "success": true,
    "message": "QR Code updated",
    "data": {
        "id": "5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d",
        "team_id": "1f2a3b4c-5d6e-4789-8abc-1234567890ab",
        "link_id": "8e9f0a1b-2c3d-4e5f-6a7b-8c9d0e1f2a3b",
        "folder_id": "9a60e0a5-2962-4217-ba5c-0b92db2c92be",
        "name": "Updated Event Banner QR",
        "design_config": {
            "dotsOptions": {
                "type": "rounded",
                "color": "#000000"
            },
            "backgroundOptions": {
                "color": "#f3f4f6"
            }
        },
        "short_url": "https://goose.re/event-promo",
        "created_at": "2026-07-04 22:26:10"
    }
}

DELETE /api/v1/qrcodes/{id}

Delete a QR code

Permanently delete the QR code record. Its associated short link remains available.

Required API key scope: qrcodes:write

Parameters

Parameter	Location	Type	Description
id *	path	string (Path Parameter)	The unique identifier of the QR code to delete.

Example response (HTTP 200)

{
    "success": true,
    "message": "QR Code deleted",
    "data": null
}

Folders

GET /api/v1/folders

List folders

Retrieve the folders in the authenticated team workspace to look up the groups used to organize campaign content.

Required API key scope: folders:read

This endpoint does not require a request body or query parameters.

Example response (HTTP 200)

{
    "success": true,
    "message": "OK",
    "data": [
        {
            "id": "9a60e0a5-2962-4217-ba5c-0b92db2c92be",
            "name": "Marketing Campaigns",
            "created_at": "2026-06-01 10:00:00"
        }
    ]
}

POST /api/v1/folders

Create a folder

Create a folder in the authenticated team workspace. The key creator must be a team owner or admin.

Required API key scope: folders:write

Parameters

Parameter	Location	Type	Description
name *	body	string	Folder name, 1–50 characters.
color	body	string	Folder color. Default: `#3B82F6`
icon	body	string	Font Awesome icon class. Default: `fa-folder`

Example request body

{
    "name": "Q3 Launch Assets"
}

Example response (HTTP 201)

{
    "success": true,
    "message": "Folder created",
    "data": {
        "id": "e98a3b5c-42cd-4389-9804-09852be9081e",
        "name": "Q3 Launch Assets",
        "created_at": "2026-07-04 22:19:50",
        "color": "#3B82F6",
        "icon": "fa-folder"
    }
}