U301 API reference

New to Corsair? See API access, authentication, and error handling.

Analytics

audience

analytics.audience Read a top-N click breakdown by country, city, referrer, browser, OS or device Risk: read

await corsair.u301.api.analytics.audience({ dimension: 'countries', range: '30d' });

Input

Name	Type	Required	Description
`dimension`	`countries \| cities \| referers \| browsers \| operating-systems \| device-types`	Yes	Which breakdown to read: countries, cities, referers, browsers, operating-systems or device-types.
`range`	`24h \| 1d \| 3d \| 7d \| 14d \| 30d \| 60d \| 1m`	Yes	The window to aggregate over.
`timezone`	`string`	No	An IANA timezone for the buckets. Defaults to UTC.

Output

Name	Type	Required	Description
`datetimeRange`	`string[] \| null`	No	—
`range`	`string \| null`	No	—
`data`	`object[] \| null`	No	—

data full type

{
  label?: string | null,
  click?: number | null,
  meta?: Record<string, any> | null
}[] | null

clicks

analytics.clicks Read click counts over a time range at a chosen granularity, in a chosen timezone Risk: read

await corsair.u301.api.analytics.clicks({ range: '7d', granularity: 'day', timezone: 'UTC' });

Input

Name	Type	Required	Description
`range`	`24h \| 1d \| 3d \| 7d \| 14d \| 30d \| 60d \| 1m`	Yes	The window to aggregate over.
`granularity`	`day \| hour`	Yes	The bucket size within that window.
`timezone`	`string`	No	An IANA timezone for the buckets. Defaults to UTC.

Output

Name	Type	Required	Description
`start`	`string \| null`	No	ISO 8601 start of the window.
`end`	`string \| null`	No	ISO 8601 end of the window.
`data`	`object[] \| null`	No	One entry per bucket.

data full type

{
  date?: string | null,
  click?: number | null
}[] | null

Domains

active

domains.active Check whether a domain’s DNS verification has completed, which is the step to poll after adding the CNAME Risk: read

await corsair.u301.api.domains.active({ domain: 'go.example.com' });

Input

Name	Type	Required	Description
`domain`	`string`	Yes	The domain for the link, such as u301.co or one of your own.

Output

Name	Type	Required	Description
`actived`	`boolean \| null`	No	Whether the domain is active.
`message`	`string \| null`	No	—

create

domains.create Add a custom domain; the DNS CNAME still has to be created and verified before it serves links Risk: write

await corsair.u301.api.domains.create({ domain: 'go.example.com', shortCodeLength: 5 });

Input

Name	Type	Required	Description
`domain`	`string`	Yes	The domain for the link, such as u301.co or one of your own.
`shortCodeLength`	`number`	No	Length of the random slug, 3 to 10. Defaults to 6.

Output

Name	Type	Required	Description
`message`	`string \| null`	No	”Domain created” on success.
`success`	`true \| null`	No	—

delete

domains.delete Remove a custom domain from the workspace Risk: destructive

await corsair.u301.api.domains.delete({ domain: 'go.example.com' });

Input

Name	Type	Required	Description
`domain`	`string`	Yes	The domain for the link, such as u301.co or one of your own.

Output

Name	Type	Required	Description
`message`	`string \| null`	No	”success” on deletion.
`success`	`true \| null`	No	—

get

domains.get Read one domain’s validity, archive state, slug length and redirect settings Risk: read

await corsair.u301.api.domains.get({ domain: 'go.example.com' });

Input

Name	Type	Required	Description
`domain`	`string`	Yes	The domain for the link, such as u301.co or one of your own.

Output

Name	Type	Required	Description
`domain`	`string \| null`	No	—
`isValid`	`boolean \| null`	No	—
`isArchived`	`boolean \| null`	No	—
`lastCheckedAt`	`string \| null`	No	—
`randomCodeLength`	`number \| null`	No	—
`workspaceId`	`string \| null`	No	—
`homePageRedirectUrl`	`string \| null`	No	—
`notFoundPageRedirectUrl`	`string \| null`	No	—
`createdAt`	`string \| null`	No	—
`updatedAt`	`string \| null`	No	—
`isPrimary`	`boolean \| null`	No	—
`isGlobal`	`boolean \| null`	No	True for a U301-owned domain.
`dnsSettings`	`object \| null`	No	—

dnsSettings full type

{
  cnameValue?: string | null,
  isHostedOnCloudflare?: boolean | null,
  baseDomain?: string | null,
  subdomain?: string | null,
  domainConnectUrl?: string | null,
  cloudflareAuthUrl?: string | null
} | null

homeRedirect

domains.homeRedirect Set where a domain’s root redirects to; U301 allows it on the Pro plan only and answers 403 on the free plan Risk: write

await corsair.u301.api.domains.homeRedirect({ domain: 'go.example.com', homePageRedirectUrl: 'https://example.com' });

Input

Name	Type	Required	Description
`domain`	`string`	Yes	The domain for the link, such as u301.co or one of your own.
`homePageRedirectUrl`	`string`	Yes	Where the domain root redirects to.

Output

Name	Type	Required	Description
`success`	`true`	Yes	—

list

domains.list List the workspace’s domains, including the shared u301.co and any of your own Risk: read

await corsair.u301.api.domains.list({});

Input: empty object Output: object[]

Output full type

{
  domain?: string | null,
  randomCodeLength?: number | null,
  isPrimary?: boolean | null,
  isGlobal?: boolean | null
}[]

notFoundRedirect

domains.notFoundRedirect Set where an unknown slug on a domain redirects to; U301 allows it on the Pro plan only and answers 403 on the free plan Risk: write

await corsair.u301.api.domains.notFoundRedirect({ domain: 'go.example.com', notFoundPageRedirectUrl: 'https://example.com/404' });

Input

Name	Type	Required	Description
`domain`	`string`	Yes	The domain for the link, such as u301.co or one of your own.
`notFoundPageRedirectUrl`	`string`	Yes	Where an unknown slug on this domain redirects to.

Output

Name	Type	Required	Description
`success`	`true`	Yes	—

pathLength

domains.pathLength Set the random slug length a domain uses, 3 to 10 Risk: write

await corsair.u301.api.domains.pathLength({ domain: 'go.example.com', randomCodeLength: 8 });

Input

Name	Type	Required	Description
`domain`	`string`	Yes	The domain for the link, such as u301.co or one of your own.
`randomCodeLength`	`number`	Yes	Length of the random slug, 3 to 10.

Output

Name	Type	Required	Description
`success`	`true`	Yes	—

Links

create

links.create Shorten a URL on u301.co or one of your domains, with an optional custom slug, password and comment; a new link spends one monthly allowance slot Risk: write

await corsair.u301.api.links.create({ url: 'https://example.com/spring-sale', slug: 'spring', comment: 'spring campaign' });

Input

Name	Type	Required	Description
`url`	`string`	Yes	The destination URL to shorten.
`domain`	`string`	No	The domain for the link, such as u301.co or one of your own.
`slug`	`string`	No	A custom path. A random one is generated when omitted.
`reuseExisting`	`boolean`	No	Reuse an existing short link when the same URL is already shortened, instead of creating a second one.
`password`	`string`	No	Require this password before the short link resolves.
`comment`	`string`	No	A note to attach to the link.

Output

Name	Type	Required	Description
`id`	`string \| null`	No	—
`url`	`string \| null`	No	The destination URL.
`slug`	`string \| null`	No	—
`isCustomSlug`	`boolean \| null`	No	—
`domain`	`string \| null`	No	—
`isReused`	`boolean \| null`	No	True when an existing link was returned and no new one was created.
`shortLink`	`string \| null`	No	The short link without a scheme, such as u301.co/jtyZ.
`comment`	`string \| null`	No	—

delete

links.delete Delete a short link; the destination is no longer reachable through it Risk: destructive

await corsair.u301.api.links.delete({ shortlink: 'u301.co/jtyZ' });

Input

Name	Type	Required	Description
`shortlink`	`string`	Yes	The short link as it appears, such as u301.co/abc123. It is sent as one path segment.

Output

Name	Type	Required	Description
`message`	`string \| null`	No	”success” on deletion.

get

links.get Read one short link by its short form, such as u301.co/abc123 Risk: read

await corsair.u301.api.links.get({ shortlink: 'u301.co/jtyZ' });

Input

Name	Type	Required	Description
`shortlink`	`string`	Yes	The short link as it appears, such as u301.co/abc123. It is sent as one path segment.

Output

Name	Type	Required	Description
`id`	`string \| null`	No	—
`domainName`	`string \| null`	No	The domain, on a list row.
`domain`	`string \| null`	No	The domain, on a single read.
`slug`	`string \| null`	No	—
`isCustomSlug`	`boolean \| null`	No	—
`shortUrl`	`string \| null`	No	—
`originalUrl`	`string \| null`	No	The destination URL.
`allowSearchEngineIndexing`	`boolean \| null`	No	—
`archived`	`boolean \| null`	No	—
`suspended`	`boolean \| null`	No	—
`statsClicks`	`number \| null`	No	Total clicks.
`expiresAt`	`string \| null`	No	Null when the link never expires.
`userId`	`string \| null`	No	—
`workspaceId`	`string \| null`	No	—
`comment`	`string \| null`	No	—
`createdAt`	`string \| null`	No	—
`updatedAt`	`string \| null`	No	—

list

links.list List the workspace’s short links with their click counts, archive and suspend state Risk: read

await corsair.u301.api.links.list({ page: 1, perPage: 20 });

Input

Name	Type	Required	Description
`page`	`number`	No	1-based page number.
`perPage`	`number`	No	Items per page, 10 to 200. Defaults to 20.

Output

Name	Type	Required	Description
`links`	`object[]`	Yes	—
`metadata`	`object`	Yes	—

links full type

{
  id?: string | null,
  domainName?: string | null,
  domain?: string | null,
  slug?: string | null,
  isCustomSlug?: boolean | null,
  shortUrl?: string | null,
  originalUrl?: string | null,
  allowSearchEngineIndexing?: boolean | null,
  archived?: boolean | null,
  suspended?: boolean | null,
  statsClicks?: number | null,
  expiresAt?: string | null,
  userId?: string | null,
  workspaceId?: string | null,
  comment?: string | null,
  createdAt?: string | null,
  updatedAt?: string | null
}[]

metadata full type

{
  total?: number | null,
  perPage?: number | null,
  page?: number | null
}

Overview

Plugins

U301 API reference

Analytics

audience

clicks

Domains

active

create

delete

get

homeRedirect

list

notFoundRedirect

pathLength

Links

create

delete

get

list

​Analytics

​audience

​clicks

​Domains

​active

​create

​delete

​get

​homeRedirect

​list

​notFoundRedirect

​pathLength

​Links

​create

​delete

​get

​list

Analytics

audience

clicks

Domains

active

create

delete

get

homeRedirect

list

notFoundRedirect

pathLength

Links

create

delete

get

list