Link

GET/api/v1/links

List_links

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Conditions as filter[][]=. Conditions on different fields all apply. in (any of) and all (every one of, on fields holding several values) take a comma-separated list (\, for a literal comma). exists takes true or false. Datetimes are RFC 3339, now, or a time before now such as -30m, -6h or -7d.

sort?string

Comma-separated sort keys, - for descending, at most 1. Keys: slug, policy_version, created_at. Default: -created_at.

limit?integer

Rows per page, 1 to 100 (default 25).

Range1 <= value <= 100

cursor?string

The page.next_cursor of the previous page. Cannot be combined with page.

page?integer

A 1-based page number, for jumping. Cannot be combined with cursor.

Range1 <= value

total?boolean

Set to true to include the number of matching rows in page.total.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/links"

{  "links": [    {      "campaign_id": "string",      "created_at": "2019-08-24T14:15:22Z",      "destination_url": "string",      "domain": "string",      "link_id": "string",      "short_url": "string",      "slug": "string",      "status": "draft",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "page": {    "has_more": true,    "next_cursor": "string",    "page": 0,    "total": 0  }}

POST/api/v1/links

Create_link

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

campaign_id*string

Campaign the link belongs to

conditional_routes?array<>

Ordered conditional routes

destination_url*string

Destination URL

domain?|

Branded domain (defaults to the campaign default domain)

expires_at?|

Expiry time for the link

Formatdate-time

max_clicks?|

Maximum total clicks before the link expires

Formatint64

Range0 <= value

password?|

Plaintext password protecting the link. Stored only as a secret reference.

pixel_ids?array<string>

Pixel ids fired on redirect

pixel_tracking_enabled?boolean

Enable pixel tracking

qr_code_enabled?boolean

Enable QR code generation

security_cloaking?

Enable security cloaking

slug?|

Explicit vanity slug. When omitted a short slug is generated.

starts_at?|

Start time for the link

Formatdate-time

utm?

Link-level UTM overrides

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/links" \  -H "Content-Type: application/json" \  -d '{    "campaign_id": "string",    "destination_url": "string"  }'

{  "link_id": "string",  "qr_code_blob_id": "string",  "short_url": "string",  "slug": "string",  "status": "draft"}

POST/api/v1/links/batch

Create many links in one request

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

A batch of links to create under one or more campaigns. Links are created independently and fail-fast (slug collisions are per-link); the server enforces a per-batch cap.

links*array<>

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/links/batch" \  -H "Content-Type: application/json" \  -d '{    "links": [      {        "campaign_id": "string",        "destination_url": "string"      }    ]  }'

{  "count": 0,  "links": [    {      "link_id": "string",      "qr_code_blob_id": "string",      "short_url": "string",      "slug": "string",      "status": "draft"    }  ]}

GET/api/v1/links/campaigns

List_campaigns

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Query Parameters

filter?

q?string

Full-text search over this list's searchable fields.

Length1 <= length <= 200

sort?string

Comma-separated sort keys, - for descending, at most 1. Keys: name, active_link_count, created_at. Default: -created_at.

limit?integer

Rows per page, 1 to 100 (default 25).

Range1 <= value <= 100

cursor?string

The page.next_cursor of the previous page. Cannot be combined with page.

page?integer

A 1-based page number, for jumping. Cannot be combined with cursor.

Range1 <= value

total?boolean

Set to true to include the number of matching rows in page.total.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/links/campaigns"

{  "campaigns": [    {      "active_link_count": 0,      "agent_context_policy": {        "allow_tracking_pixel": true,        "allowed_agents": [          "string"        ],        "enabled": true,        "max_added_query_params": 0      },      "campaign_id": "string",      "created_at": "2019-08-24T14:15:22Z",      "created_by": "string",      "default_domain": "string",      "default_utm": {        "campaign": "string",        "content": "string",        "medium": "string",        "source": "string",        "term": "string"      },      "description": "string",      "name": "string",      "security_policy": {        "blocked_reputation_buckets": [          "trusted"        ],        "cloak_unknown_referrers": true,        "password_required_by_default": true      },      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "page": {    "has_more": true,    "next_cursor": "string",    "page": 0,    "total": 0  }}

POST/api/v1/links/campaigns

Create_campaign

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

agent_context_policy?

Agent context policy

default_domain*string

Default branded domain

default_utm?

Default UTM parameters appended to links in this campaign

description?|

Optional description

name*string

Campaign name

security_policy?

Security policy

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/links/campaigns" \  -H "Content-Type: application/json" \  -d '{    "default_domain": "string",    "name": "string"  }'

{  "campaign_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "default_domain": "string",  "name": "string"}

GET/api/v1/links/campaigns/{campaign_id}

Get_campaign

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

campaign_id*string

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/links/campaigns/string"

{  "active_link_count": 0,  "agent_context_policy": {    "allow_tracking_pixel": true,    "allowed_agents": [      "string"    ],    "enabled": true,    "max_added_query_params": 0  },  "campaign_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "created_by": "string",  "default_domain": "string",  "default_utm": {    "campaign": "string",    "content": "string",    "medium": "string",    "source": "string",    "term": "string"  },  "description": "string",  "name": "string",  "security_policy": {    "blocked_reputation_buckets": [      "trusted"    ],    "cloak_unknown_referrers": true,    "password_required_by_default": true  },  "updated_at": "2019-08-24T14:15:22Z"}

GET/api/v1/links/campaigns/{campaign_id}/stats

Get_campaign_stats

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

campaign_id*string

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/links/campaigns/string/stats"

{  "active_link_count": 0,  "campaign_id": "string",  "outcome_breakdown": {    "property1": 0,    "property2": 0  },  "total_clicks": 0,  "unique_visitors": 0}

GET/api/v1/links/domains

List_domains

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Query Parameters

filter?

sort?string

Comma-separated sort keys, - for descending, at most 1. Keys: campaign_count, domain. Default: domain.

limit?integer

Rows per page, 1 to 100 (default 25).

Range1 <= value <= 100

cursor?string

The page.next_cursor of the previous page. Cannot be combined with page.

page?integer

A 1-based page number, for jumping. Cannot be combined with cursor.

Range1 <= value

total?boolean

Set to true to include the number of matching rows in page.total.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/links/domains"

{  "domains": [    {      "campaign_count": 0,      "domain": "string",      "verified": true    }  ],  "page": {    "has_more": true,    "next_cursor": "string",    "page": 0,    "total": 0  }}

GET/api/v1/links/{link_id}

Get_link

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

link_id*string

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/links/string"

{  "campaign_id": "string",  "conditional_routes": [    {      "destination_url": "string",      "fallback_url": "string",      "name": "string",      "skip_utm": true,      "when": {        "country_allowlist": [          "string"        ],        "device_family": "string",        "referrer_class": "string",        "reputation_min": null      }    }  ],  "created_at": "2019-08-24T14:15:22Z",  "created_by": "string",  "destination_url": "string",  "domain": "string",  "link_id": "string",  "password": {    "enabled": true,    "hash_ref": "string"  },  "pixel_tracking": {    "enabled": true,    "pixel_ids": [      "string"    ]  },  "policy_version": 0,  "qr_code": {    "blob_id": "string",    "enabled": true,    "policy_version": 0  },  "security_cloaking": {    "enabled": true,    "interstitial_url": "string"  },  "short_url": "string",  "slug": "string",  "status": "draft",  "ttl": {    "expires_at": "2019-08-24T14:15:22Z",    "max_clicks": 0,    "starts_at": "2019-08-24T14:15:22Z"  },  "updated_at": "2019-08-24T14:15:22Z",  "utm": {    "campaign": "string",    "content": "string",    "medium": "string",    "source": "string",    "term": "string"  }}

PATCH/api/v1/links/{link_id}

Update_link

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

link_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

conditional_routes?array<>|

Replacement conditional routes

destination_url?|

New destination URL

expires_at?|

New expiry time

Formatdate-time

max_clicks?|

New maximum click count

Formatint64

Range0 <= value

password?|

Set or clear the password. An empty string clears protection.

pixel_tracking?null|

security_cloaking?null|

slug?|

New slug (collision-checked)

status?null|

utm?null|

Response Body

`application/json`

curl -X PATCH "https://example.com/api/v1/links/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "campaign_id": "string",  "conditional_routes": [    {      "destination_url": "string",      "fallback_url": "string",      "name": "string",      "skip_utm": true,      "when": {        "country_allowlist": [          "string"        ],        "device_family": "string",        "referrer_class": "string",        "reputation_min": null      }    }  ],  "created_at": "2019-08-24T14:15:22Z",  "created_by": "string",  "destination_url": "string",  "domain": "string",  "link_id": "string",  "password": {    "enabled": true,    "hash_ref": "string"  },  "pixel_tracking": {    "enabled": true,    "pixel_ids": [      "string"    ]  },  "policy_version": 0,  "qr_code": {    "blob_id": "string",    "enabled": true,    "policy_version": 0  },  "security_cloaking": {    "enabled": true,    "interstitial_url": "string"  },  "short_url": "string",  "slug": "string",  "status": "draft",  "ttl": {    "expires_at": "2019-08-24T14:15:22Z",    "max_clicks": 0,    "starts_at": "2019-08-24T14:15:22Z"  },  "updated_at": "2019-08-24T14:15:22Z",  "utm": {    "campaign": "string",    "content": "string",    "medium": "string",    "source": "string",    "term": "string"  }}

DELETE/api/v1/links/{link_id}

Delete_link

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

link_id*string

Response Body

`application/json`

curl -X DELETE "https://example.com/api/v1/links/string"

{  "deleted": true,  "link_id": "string"}

POST/api/v1/links/{link_id}/password/verify

Verify_password

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

link_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

password*string

Password to verify

visitor_hash?|

Visitor hash for failed-attempt rate limiting

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/links/string/password/verify" \  -H "Content-Type: application/json" \  -d '{    "password": "string"  }'

{  "expires_in_seconds": 0,  "link_id": "string",  "redirect_token": "string",  "verified": true}

POST/api/v1/links/{link_id}/qr

Generate_qr

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

link_id*string

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/links/string/qr"

{  "blob_id": "string",  "content_type": "string",  "image_base64": "string",  "link_id": "string",  "policy_version": 0,  "size": 0}

POST/api/v1/links/{link_id}/quarantine

Quarantine_link

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

link_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

interstitial_url?|

Optional interstitial URL to route callers to

reason?|

Reason for quarantine

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/links/string/quarantine" \  -H "Content-Type: application/json" \  -d '{}'

{  "link_id": "string",  "message": "string",  "status": "draft"}

POST/api/v1/links/{link_id}/resolve

Resolve_link

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

link_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

agent_id?|

Requested agent id for agent-injected context

country?|

Country code for allowlist evaluation

device_family?|

Device family hint (e.g. ios, android, desktop)

redirect_token?|

Short-lived redirect token from a prior password verification

referrer_class?|

Referrer class hint

reputation_bucket?null|

request_id?|

Request id for hot-path dedupe

visitor_hash?|

Visitor hash for unique visitor estimation

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/links/string/resolve" \  -H "Content-Type: application/json" \  -d '{}'

{  "agent_id": "string",  "campaign_id": "string",  "final_url": "string",  "injected_params": [    "string"  ],  "interstitial_url": "string",  "link_id": "string",  "outcome": "redirected",  "selected_route": "string",  "tracking_pixels": [    "string"  ]}

GET/api/v1/links/{link_id}/stats

Get_stats

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

link_id*string

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/links/string/stats"

{  "campaign_id": "string",  "link_id": "string",  "outcome_breakdown": {    "property1": 0,    "property2": 0  },  "route_breakdown": {    "property1": 0,    "property2": 0  },  "total_clicks": 0,  "unique_visitors": 0}

GET/r/{slug}

curl -X GET "https://example.com/r/string"

Empty

200application/json

400

503

201application/json

400

409

503

201application/json

400

401

409

200application/json

400

503

201application/json

400

503

200application/json

404

503

200application/json

404

503

200application/json

400

503

200application/json

404

503

200application/json

404

409

503

200application/json

403

404

503

200application/json

401

429

503

200application/json

404

503

200application/json

404

503

200application/json

404

503

200application/json

404

503

307

401

403

404

410

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`