API Reference

Build custom integrations, automate workflows, and connect Goose.re with your existing tools using our RESTful API.

Introduction

The Goose.re API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL


                        https://api.goose.re/api/v1

Authentication

The Goose.re API uses API keys to authenticate requests. You can view and manage your API keys in the dashboard under your Team Settings.

Authentication to the API is performed via HTTP Bearer Auth. Provide your API key as the bearer token value.

Example Request

curl https://api.goose.re/api/v1/links \
  -H "Authorization: Bearer goose_live_xxxxxxxxxxxxxxxxx"

AI Agents & Tooling

Machine Readable

Goose.re provides structured documentation optimized for Large Language Models, autonomous agents, and internal developer platforms.

OpenAPI Specification

Download the full, machine-readable OpenAPI 3.0 specification file.

View openapi.json →

System Instructions

Use our optimized context prompt to feed directly into your agent's system prompt.

View llms.txt →

Links

POST /api/v1/links

Create a new link

Shorten a new URL. You can apply custom slugs, custom domains, and organizational folders directly during creation.

Parameters

Parameter	Type	Description
destination *	string	The long destination URL to shorten.
slug	string	Custom alias / suffix for the shortened link. Auto-generated if omitted.
domain_id	string (UUID)	Target custom domain ID.
folder_id	string (UUID)	Organize into this specific folder ID.
title	string	Friendly label for your links in the dashboard.

Request Payload

{
    "destination": "https://example.com/very-long-url-path-here",
    "slug": "my-promo",
    "domain_id": "1d6f5195-2fc4-4740-974d-965768e1abcf",
    "folder_id": "9a60e0a5-2962-4217-ba5c-0b92db2c92be",
    "title": "Summer Promo Link"
}

Example Response

{
    "id": "3f381c81-8178-4ef8-a532-3532f7a9d0a6",
    "destination_url": "https://example.com/very-long-url-path-here",
    "slug": "my-promo",
    "short_url": "https://goose.re/my-promo",
    "domain_id": "1d6f5195-2fc4-4740-974d-965768e1abcf",
    "folder_id": "9a60e0a5-2962-4217-ba5c-0b92db2c92be",
    "title": "Summer Promo Link",
    "clicks": 0,
    "is_active": 1,
    "created_at": "2026-07-04T22:19:50Z"
}

GET /api/v1/links

List all links

Retrieve a paginated, searchable list of your team's shortened links.

Parameters

Parameter	Type	Description
limit	integer	Number of results to return. Default: `50`
offset	integer	Number of results to skip.
search	string	Search term filtering by title, slug, or destination URL.

Example Response

[
    {
        "id": "3f381c81-8178-4ef8-a532-3532f7a9d0a6",
        "destination_url": "https://example.com/very-long-url-path-here",
        "slug": "my-promo",
        "short_url": "https://goose.re/my-promo",
        "clicks": 241,
        "created_at": "2026-07-01T12:00:00Z"
    },
    {
        "id": "db0e2b9c-7e61-4682-8280-998818dbcfb4",
        "destination_url": "https://google.com",
        "slug": "search",
        "short_url": "https://goose.re/search",
        "clicks": 89,
        "created_at": "2026-07-02T15:30:00Z"
    }
]

GET /api/v1/links/{id}

Retrieve link detail

Retrieve details of a specific shortened link using its unique identifier.

Parameters

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

Example Response

{
    "id": "3f381c81-8178-4ef8-a532-3532f7a9d0a6",
    "destination_url": "https://example.com/very-long-url-path-here",
    "slug": "my-promo",
    "short_url": "https://goose.re/my-promo",
    "domain_id": "1d6f5195-2fc4-4740-974d-965768e1abcf",
    "folder_id": "9a60e0a5-2962-4217-ba5c-0b92db2c92be",
    "title": "Summer Promo Link",
    "clicks": 241,
    "is_active": 1,
    "created_at": "2026-07-01T12:00:00Z"
}

PUT /api/v1/links/{id}

Update an existing link

Update an existing shortened link's properties (e.g. changing its destination URL or title).

Parameters

Parameter	Type	Description
id *	string (Path Parameter)	The unique identifier of the link to update.
destination	string	New target URL destination.
title	string	Updated link title.

Request Payload

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

Example Response

{
    "id": "3f381c81-8178-4ef8-a532-3532f7a9d0a6",
    "destination_url": "https://new-destination.com/page",
    "slug": "my-promo",
    "short_url": "https://goose.re/my-promo",
    "title": "Updated Campaign URL",
    "clicks": 241,
    "is_active": 1,
    "created_at": "2026-07-01T12:00:00Z"
}

DELETE /api/v1/links/{id}

Delete link

Permanently delete a shortened link from the database.

Parameters

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

Example Response

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

Bio Pages

GET /api/v1/pages

List Bio Pages

Retrieve a list of your team's active link-in-bio page URLs and details.

Parameters

Parameter	Type	Description
folder_id	string (UUID)	Filter by a specific folder ID. Pass empty string to filter for pages with no folder.
sort_by	string	Sort field: `created_at`, `title`, `slug`, or `total_clicks`.
sort_order	string	Sort direction: `asc` or `desc`.

Example Response

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

POST /api/v1/pages

Create Bio Page

Create a new interactive web portal / link-in-bio page under your profile.

Parameters

Parameter	Type	Description
slug *	string	The unique public URL slug.
title *	string	Headline title displayed at the top of the bio page.
description	string	Brief description or bio subtitle text.
theme	string	Preset theme name (e.g. `default`, `dark`, `glass`).
theme_accent_1	string (Hex Color)	Primary brand color hex string (e.g., `#ff0055`).
theme_accent_2	string (Hex Color)	Secondary brand/accent color hex string.
domain_id	string (UUID)	Custom domain configuration ID.
folder_id	string (UUID)	Target folder ID.

Request Payload

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

Example Response

{
    "id": "cf067c29-37ea-4bf0-b6c8-52c67cfc0a21",
    "team_id": "team-uuid-123",
    "slug": "developer-advocacy",
    "title": "Developer Relations Resources",
    "description": "Find all official Goose.re developer templates, toolkits, and client SDKs.",
    "theme": "glass",
    "theme_accent_1": "#6366f1",
    "created_at": "2026-07-04T22:19:50Z"
}

GET /api/v1/pages/{id}

Get Bio Page

Retrieve full page layout config, including all inner bio links and configuration for active plugins.

Parameters

Parameter	Type	Description
id *	string (Path Parameter)	Unique ID of the bio page.

Example Response

{
    "id": "cf067c29-37ea-4bf0-b6c8-52c67cfc0a21",
    "slug": "developer-advocacy",
    "title": "Developer Relations Resources",
    "links": [
        {
            "id": "link-uuid-1",
            "label": "GitHub Org",
            "url": "https://github.com/goose-re",
            "icon": "fa-github",
            "color": "#ffffff",
            "bg_color": "#24292e",
            "animation": "bounce",
            "sort_order": 1
        }
    ],
    "plugins": [
        {
            "id": "plugin-uuid-1",
            "type": "newsletter",
            "config": {
                "title": "Subscribe to newsletter",
                "placeholder": "your@email.com"
            },
            "sort_order": 2
        }
    ]
}

PUT /api/v1/pages/{id}

Update Bio Page

Modify the theme styling, title, descriptions, css overrides, and meta properties of the bio page.

Parameters

Parameter	Type	Description
id *	string (Path Parameter)	Unique ID of the page to update.
slug	string	New URL slug.
title	string	Updated title display.
description	string	Bio layout subtitle text.
profile_image	string (URL)	Avatar profile image URL.
background_image	string (URL)	Layout background image URL.
favicon	string (URL)	Custom favicon URL.
theme	string	Active theme presets.
theme_accent_1	string (Hex)	Primary theme brand color.
theme_accent_2	string (Hex)	Secondary theme brand color.
custom_css	string	CSS overrides code injected into the bio page template.

Request Payload

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

Example Response

{
    "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-04T22:19:50Z"
}

DELETE /api/v1/pages/{id}

Delete Bio Page

Permanently delete the page layout. All inner bio links and plugin registrations are deleted recursively.

Parameters

Parameter	Type	Description
id *	string (Path Parameter)	Unique ID of the page to delete.

Example Response

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

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

Add Bio Link

Append a redirect action link element to the portal grid.

Parameters

Parameter	Type	Description
id *	string (Path Parameter)	Target bio page ID.
label *	string	Title tag printed on the button.
url *	string (URL)	Destination link redirection target URL.
icon	string	FontAwesome icon identifier class.
color	string (Hex)	Label font color code (default: `#333333`).
bg_color	string (Hex)	Button background color code.
animation	string	Visual entrance / loop animation trigger (e.g. `bounce`, `none`).
sort_order	integer	Layout order layout placement index.

Request Payload

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

Example Response

{
    "id": "link-uuid-abc1",
    "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
}

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

Update Bio Link

Edit specific properties of an existing link element.

Parameters

Parameter	Type	Description
id *	string (Path Parameter)	Target bio page ID.
linkId *	string (Path Parameter)	Target link element ID.
label	string	Redefine button label.
url	string (URL)	Modify redirection target.
icon	string	FontAwesome icon name.
color	string (Hex)	Label font color.
bg_color	string (Hex)	Button background.
animation	string	Hover/Attention animation.

Request Payload

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

Example Response

{
    "id": "link-uuid-abc1",
    "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
}

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

Delete Bio Link

Remove an interactive action button link from the layout.

Parameters

Parameter	Type	Description
id *	string (Path Parameter)	Target bio page ID.
linkId *	string (Path Parameter)	Link ID to delete.

Example Response

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

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

Add Bio Plugin

Install an active layout extension widget (e.g. email capture newsletters, social widgets).

Parameters

Parameter	Type	Description
id *	string (Path Parameter)	Target page ID.
type *	string	The type identifier of the plugin widget (e.g. `newsletter`, `socials`, `spotify`).
config	object	Dynamic key/value schema parameters for plugin rendering configuration.
sort_order	integer	Rendering order position.

Request Payload

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

Example Response

{
    "id": "plugin-uuid-xyz2",
    "page_id": "cf067c29-37ea-4bf0-b6c8-52c67cfc0a21",
    "type": "socials",
    "config": {
        "twitter": "https://twitter.com/goose_re",
        "linkedin": "https://linkedin.com/company/goose-re"
    },
    "sort_order": 1
}

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

Update Bio Plugin

Update configuration settings parameters for an installed plugin.

Parameters

Parameter	Type	Description
id *	string (Path Parameter)	Target page ID.
pluginId *	string (Path Parameter)	Target plugin widget ID.
config *	object	New key/value parameters replacing config properties.
sort_order	integer	Sort rendering placement.

Request Payload

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

Example Response

{
    "id": "plugin-uuid-xyz2",
    "page_id": "cf067c29-37ea-4bf0-b6c8-52c67cfc0a21",
    "type": "socials",
    "config": {
        "twitter": "https://twitter.com/goose_re_updates",
        "linkedin": "https://linkedin.com/company/goose-re"
    },
    "sort_order": 1
}

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

Delete Bio Plugin

Remove the plugin widget from the layout.

Parameters

Parameter	Type	Description
id *	string (Path Parameter)	Target page ID.
pluginId *	string (Path Parameter)	Plugin ID to delete.

Example Response

{
    "success": true,
    "message": "Plugin deleted successfully"
}

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

Save Element Order

Reorder multiple components (both link buttons and plugin blocks) sequentially with a single post request.

Parameters

Parameter	Type	Description
id *	string (Path Parameter)	Target page ID.
items *	array of objects	List of page items. Each item must supply `id` (UUID), `type` (`link` or `plugin`), and `sort_order` (integer).

Request Payload

{
    "items": [
        {
            "id": "link-uuid-abc1",
            "type": "link",
            "sort_order": 1
        },
        {
            "id": "plugin-uuid-xyz2",
            "type": "plugin",
            "sort_order": 2
        }
    ]
}

Example Response

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

Analytics

GET /api/v1/analytics

Retrieve metrics

Fetch aggregated click analytics across all links for your team, grouped by timeseries, device, or country.

Parameters

Parameter	Type	Description
start_date	string (YYYY-MM-DD)	ISO-8601 formatted start date.
end_date	string (YYYY-MM-DD)	ISO-8601 formatted end date.
groupBy	string	Grouping interval: `day`, `week`, or `month`.

Example Response

{
    "total_clicks": 1540,
    "clicks_by_day": [
        {
            "date": "2026-07-01",
            "clicks": 450
        },
        {
            "date": "2026-07-02",
            "clicks": 510
        },
        {
            "date": "2026-07-03",
            "clicks": 580
        }
    ],
    "devices": {
        "desktop": 920,
        "mobile": 540,
        "tablet": 80
    },
    "countries": {
        "US": 800,
        "GB": 300,
        "DE": 200,
        "FR": 140,
        "Other": 100
    }
}

QR Codes

GET /api/v1/qrcodes

List QR Codes

Retrieve a list of QR codes created for your team with filtering and pagination.

Parameters

Parameter	Type	Description
search	string	Filter QR codes by name, short code, or destination URL.
folder_id	string (UUID)	Filter by a specific folder ID.
sort_by	string	Sort field: `created_at`, `name`, or `total_clicks`.
sort_order	string	Sort direction: `asc` or `desc`.
limit	integer	Number of results to return. Default: `50`
offset	integer	Number of results to skip.

Example Response

{
    "qrcodes": [
        {
            "id": "1d2e3f4g-5h6i-7j8k-9l0m-1n2o3p4q5r6s",
            "team_id": "team-uuid-123",
            "link_id": "3f381c81-8178-4ef8-a532-3532f7a9d0a6",
            "folder_id": "9a60e0a5-2962-4217-ba5c-0b92db2c92be",
            "name": "Flyer QR Campaign",
            "design_config": {
                "color": "#000000",
                "bg_color": "#ffffff",
                "logo": "https://goose.re/logo.png"
            },
            "short_url": "https://goose.re/my-promo",
            "folder_name": "Marketing Campaigns",
            "created_at": "2026-07-04T12:00:00Z",
            "updated_at": "2026-07-04T12:00:00Z"
        }
    ],
    "total": 1
}

POST /api/v1/qrcodes

Create QR Code

Generate a new custom-designed QR code. You can connect it to an existing link or provide a URL to auto-generate a new shortlink.

Parameters

Parameter	Type	Description
name *	string	The name of the QR code.
design_config *	object / JSON string	Color and styling configuration for the QR code.
url	string	Destination URL. If provided and link_id is empty, a new shortlink is auto-created.
link_id	string (UUID)	Connect the QR code directly to an existing shortlink.
folder_id	string (UUID)	Place the QR code under a specific folder.

Request Payload

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

Example Response

{
    "id": "5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d",
    "team_id": "team-uuid-123",
    "link_id": "8e9f0a1b-2c3d-4e5f-6a7b-8c9d0e1f2a3b",
    "folder_id": "9a60e0a5-2962-4217-ba5c-0b92db2c92be",
    "name": "Event Banner QR",
    "design_config": {
        "color": "#1d4ed8",
        "bg_color": "#ffffff"
    },
    "short_url": "https://goose.re/event-promo",
    "created_at": "2026-07-04T22:26:10Z",
    "updated_at": "2026-07-04T22:26:10Z"
}

GET /api/v1/qrcodes/{id}

Get QR Code

Retrieve the details of a specific QR code by ID.

Parameters

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

Example Response

{
    "id": "5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d",
    "team_id": "team-uuid-123",
    "link_id": "8e9f0a1b-2c3d-4e5f-6a7b-8c9d0e1f2a3b",
    "folder_id": "9a60e0a5-2962-4217-ba5c-0b92db2c92be",
    "name": "Event Banner QR",
    "design_config": {
        "color": "#1d4ed8",
        "bg_color": "#ffffff"
    },
    "short_url": "https://goose.re/event-promo",
    "created_at": "2026-07-04T22:26:10Z",
    "updated_at": "2026-07-04T22:26:10Z"
}

PUT /api/v1/qrcodes/{id}

Update QR Code

Update the name, design config, or associated link/folder for a QR code.

Parameters

Parameter	Type	Description
id *	string (Path Parameter)	The unique identifier of the QR code to update.
name	string	Updated name of the QR code.
design_config	object / JSON string	Updated color/style config.
link_id	string (UUID)	Update the connected shortlink.
folder_id	string (UUID)	Update the folder location.

Request Payload

{
    "name": "Updated Event Banner QR",
    "design_config": {
        "color": "#000000",
        "bg_color": "#f3f4f6"
    }
}

Example Response

{
    "id": "5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d",
    "team_id": "team-uuid-123",
    "link_id": "8e9f0a1b-2c3d-4e5f-6a7b-8c9d0e1f2a3b",
    "folder_id": "9a60e0a5-2962-4217-ba5c-0b92db2c92be",
    "name": "Updated Event Banner QR",
    "design_config": {
        "color": "#000000",
        "bg_color": "#f3f4f6"
    },
    "short_url": "https://goose.re/event-promo",
    "created_at": "2026-07-04T22:26:10Z",
    "updated_at": "2026-07-04T22:28:00Z"
}

DELETE /api/v1/qrcodes/{id}

Delete QR Code

Permanently delete a QR code.

Parameters

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

Example Response

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

Folders

GET /api/v1/folders

List folders

Retrieve all organizational link folders configured in your account.

No request body or query parameters required.

Example Response

[
    {
        "id": "9a60e0a5-2962-4217-ba5c-0b92db2c92be",
        "name": "Marketing Campaigns",
        "created_at": "2026-06-01T10:00:00Z"
    }
]

POST /api/v1/folders

Create a folder

Create a new organizational folder to group links together.

Parameters

Parameter	Type	Description
name *	string	The name of the folder.

Request Payload

{
    "name": "Q3 Launch Assets"
}

Example Response

{
    "id": "e98a3b5c-42cd-4389-9804-09852be9081e",
    "name": "Q3 Launch Assets",
    "created_at": "2026-07-04T22:19:50Z"
}