---
title: "Create a New Link"
method: POST
path: "/links"
tags: ["Links"]
---

# Create a New Link

`POST /links`

## Request

- Base URL: `https://api.rebrandly.com/v1`
- URL: `https://api.rebrandly.com/v1/links`
- Auth: API key in header `apikey`

Creates a new branded short link in the specified workspace.

**Authorization:**
- Requires valid `apikey` header
- Requires `Workspace` header to specify the workspace

**Validation:**
- `destination` must be a valid URL
- `domainId` must reference a verified domain shared with the workspace
- `slashtag` must be unique for the domain (auto-generated if not provided)
- `slashtag` length must comply with domain settings

**Features:**
- `links.notes` feature allows `description` field
- Link TTL is calculated based on workspace features

## Headers

- `Workspace` string, required
- `apikey` string, required

## Request body

- object
  - `destination` string, uri, required: Target URL where the short link redirects
  - `domainId` string: Public ID of the domain to use (must be verified and shared with workspace)
  - `domain` object: Alternative way to specify domain (legacy)
    - `id` string
  - `slashtag` string: Custom path component (auto-generated if not provided, must be unique)
  - `title` string: Human-readable title for the link
  - `description` string: Link description (requires `links.notes` feature)

## Response `200`

Successfully created link

- Link
  - `id` string, required: Link public ID (link_public_id)
  - `title` string: Human-readable title for the link
  - `slashtag` string, required: URL path component
  - `destination` string, uri, required: Target URL where the link redirects
  - `shortUrl` string, required: Complete short URL (domain + slashtag)
  - `domainId` string: Public ID of the domain used
  - `domainName` string: Full domain name
  - `domain` object: Domain object with details
    - `id` string
    - `ref` string
    - `fullName` string
    - `sharing` object
  - `clicks` integer: Number of clicks on the link
  - `createdAt` string, date-time, required: Timestamp when link was created
  - `updatedAt` string, date-time, required: Timestamp when link was last updated
  - `status` 'active' | 'deleted' | 'blocked', required: Link status
  - `description` string: Link description (only if links.notes feature is enabled)
  - `workspace` object: Workspace information
    - `id` string: Workspace public ID
  - `https` boolean: Whether the link supports HTTPS

## Other responses

- `400`: Bad Request - Invalid input
- `401`: Unauthorized - Missing or invalid authentication
- `403`: Forbidden - Validation error or insufficient permissions
- `404`: Not Found - Domain not found or not shared with workspace

---

[API](https://skmtc.dev/rebrandly/apis/rebrandly-api.md) - [All operations](https://skmtc.dev/rebrandly/apis/rebrandly-api/llms.txt) - [OpenAPI document](https://skmtc.dev/rebrandly/apis/rebrandly-api/revisions/b098bf9fb684?raw)