(POST) Create links

Create one or more links in a single request. Each link requires a destination URL and collection ID.

Endpoint

POST /api/links

Create one or more links in a single request. This endpoint accepts an array of link objects, allowing you to create multiple links efficiently in one API call.

Each link requires a destination URL and a collection ID. A unique short ID is automatically generated for each link, producing a short URL under https://hoko.to.

You can include rich metadata such as titles, descriptions, images, UTM parameters, and custom external IDs to organize and track your links effectively.

Endpoint text

POST /api/links

Authentication

Requires authentication with an API key that has the linksWrite scope.

Request Body

The request body must be an array of link objects. Each object represents one link to create.

You can create up to 10,000 links in a single request. However, the actual maximum may be lower based on your subscription plan limits and available resources.

Parameter	Type	Required	Description
`url` (body)	string (URL)	Yes	The destination URL that the short link will redirect to. Must be a valid HTTP/HTTPS URL.
`collectionId` (body)	string (UUID)	Yes	The ID of the collection (folder) to organize this link. The collection must exist in your workspace.
`title` (body)	string	No	A descriptive title for the link. Useful for organization and identification.
`description` (body)	string	No	Additional description or notes about the link.
`image` (body)	string (URL)	No	A preview image URL for the link. Must be a valid HTTP/HTTPS URL.
`utm` (body)	object	No	UTM parameters for campaign tracking. Supports source, medium, campaign, term, content, and referral.
`externalId` (body)	string	No	A custom external ID for syncing with external systems. Must be unique within your workspace.
`tenantId` (body)	string	No	A tenant identifier for multi-tenant scenarios. Useful for segmenting links by customer or organization.
`partnerId` (body)	string (UUID)	No	The ID of the partner associated with this link. Used for affiliate and partner attribution tracking.

Plan Limits

The actual maximum number of links you can create per request may be lower than 10,000 based on your subscription plan limits and available resources. The system will enforce both the hard limit (10,000) and your plan-specific limits.

Examples

Request cURL

curl -X POST "https://hoko.to/api/links" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "url": "https://example.com",
      "title": "Example Link",
      "description": "An example link",
      "collectionId": "550e8400-e29b-41d4-a716-446655440000",
      "utm": {
        "source": "google",
        "medium": "cpc",
        "campaign": "summer"
      }
    }
  ]'

Request JavaScript

const response = await fetch("https://hoko.to/api/links", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <API_KEY>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify([
    {
      url: "https://example.com",
      title: "Example Link",
      description: "An example link",
      collectionId: "550e8400-e29b-41d4-a716-446655440000",
      utm: {
        source: "google",
        medium: "cpc",
        campaign: "summer"
      }
    }
  ])
});
const links = await response.json();

Response json

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://example.com",
    "shortUrl": "https://hoko.to/abc123",
    "title": "Example Link",
    "description": "An example link",
    "collectionId": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2024-01-01T00:00:00Z"
  }
]

Important Constraints

The collectionId must reference an existing collection in your workspace. The externalId must be unique within your workspace if provided. Plan limits may restrict the number of links you can create per request and overall.