(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 and QR code URL under https://hoko.to.

You can include rich metadata such as titles, descriptions, images, UTM parameters, tag IDs, 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.

ParameterTypeRequiredDescription
url (body)string (URL)YesThe destination URL that the short link will redirect to. Must be a valid HTTPS URL.
collectionId (body)string (UUID)YesThe ID of the collection (folder) to organize this link. The collection must exist in your workspace.
tagIds (body)string[]NoExisting tag IDs to assign to this link. Every tag must already exist in your workspace.
title (body)stringNoA descriptive title for the link. Useful for organization and identification.
description (body)stringNoAdditional description or notes about the link.
image (body)string (URL)NoA preview image URL for the link. Must be a valid HTTPS URL.
utm (body)objectNoUTM parameters for campaign tracking. Create requests accept string values for source, medium, campaign, term, content, and referral.
expiresAt (body)stringNoISO date-time when the link should expire. Requires a plan with link expiration.
expiredUrl (body)string (URL)NoDestination used after expiration. Requires a plan with link expiration.
password (body)stringNoPassword required before resolving the destination. Requires a plan with password protection.
cloaked (body)booleanNoRender the resolved destination in an iframe. The destination is preflighted and rejected with 400 if it currently blocks iframe rendering. Requires a plan with link cloaking.
ios (body)string (URL)NoDestination for iOS visitors. Requires a plan with device targeting.
android (body)string (URL)NoDestination for Android visitors. Requires a plan with device targeting.
geo (body)object/nullNoCountry-code destination map such as `{ "SA": "https://example.com/sa" }`; send null or omit for no geo targeting. Requires geo targeting when set.
externalId (body)stringNoA custom external ID for syncing with external systems. Must be unique within your workspace.
tenantId (body)stringNoA tenant identifier for multi-tenant scenarios. Useful for segmenting links by customer or organization.
partnerId (body)string (UUID)NoThe 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",
      "tagIds": ["7c4e4a56-f3bb-43e9-9dc7-2f4bda07c8f0"],
      "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',
			tagIds: ['7c4e4a56-f3bb-43e9-9dc7-2f4bda07c8f0'],
			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",
		"qrCode": "https://hoko.to/qrcode?text=https%3A%2F%2Fhoko.to%2Fabc123%3Fqr%3D1&size=512&errorCorrection=H&foreground=000000&background=FFFFFF&margin=1&format=svg",
		"title": "Example Link",
		"description": "An example link",
		"image": null,
		"utm": null,
		"expiresAt": null,
		"expiredUrl": null,
		"password": null,
		"cloaked": false,
		"ios": null,
		"android": null,
		"geo": null,
		"collectionId": "550e8400-e29b-41d4-a716-446655440000",
		"tagIds": [
			"7c4e4a56-f3bb-43e9-9dc7-2f4bda07c8f0"
		],
		"externalId": null,
		"tenantId": null,
		"partnerId": null,
		"createdAt": "2024-01-01T00:00:00Z"
	}
]

Important Constraints

The collectionId must reference an existing collection in your workspace. Each tagIds value must reference an existing tag 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.