The VitraVia API

The workspace this key belongs to, the member it acts as, and its scopes. Needs no scope.

{
  "data": {
    "workspace": { "id": 1, "name": "Acme", "plan": "pro", "timezone": "Europe/Paris" },
    "user": { "id": 9, "name": "Ada Lovelace", "role": "admin" },
    "scopes": ["links:read", "links:write", "stats:read"]
  }
}

{
  "data": [
    { "id": 3, "hostname": "go.acme.com", "type": "custom", "verified": true, "isDefault": true, "createdAt": "…" }
  ]
}

Newest first. All filters are optional and combine.

curl "https://my.vitravia.app/api/v1/links?tag=7&status=active&limit=50" -H "Authorization: Bearer $VITRAVIA_API_KEY"

One link.

One link, found by its short URL rather than its id — for when what you have is go.acme.com/spring. Returns the same object as GET /links/:id, whose id then works with every other route.

curl "https://my.vitravia.app/api/v1/links/lookup?domain=go.acme.com&slug=spring" -H "Authorization: Bearer $VITRAVIA_API_KEY"

Creates a link and returns it with 201. The workspace's plan limit on links applies.

curl -X POST https://my.vitravia.app/api/v1/links \
  -H "Authorization: Bearer $VITRAVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "https://acme.com/sale",
    "slug": "spring",
    "tags": [7],
    "utm": { "source": "newsletter" }
  }'

Changes some of a link's fields and returns the updated link. Send only what you want to change. A link's domain cannot be changed — create a new link instead.

curl -X PATCH https://my.vitravia.app/api/v1/links/482 \
  -H "Authorization: Bearer $VITRAVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "destination": "https://acme.com/sale-extended", "utm": { "campaign": "spring-26" } }'

Deletes a link for good: the short URL stops resolving and the slug becomes free again. To hide a link but keep it working, PATCH it with { "archived": true } instead. Answers 204.

Alphabetical. Paginated.

One tag.

name and/or color. Renaming also updates the slug.

Removes the tag from every link that had it. The links are not touched otherwise.

In the order the dashboard shows them. Paginated.

One folder.

Any of name, description, parent. parent: null moves the folder to the top level. A folder that has sub-folders cannot be nested.

Deletes the folder only. Its links stay, unfiled; its sub-folders move to the top level.

Totals, a time series, the top countries, referrers and devices, and up to 25 of the most recent human clicks. changePct compares with the period just before; it is null for all, or when there was no traffic to compare with. Each breakdown lists up to 25 values, with the long tail folded into (other).

curl "https://my.vitravia.app/api/v1/links/482/analytics?range=30d" -H "Authorization: Bearer $VITRAVIA_API_KEY"

{
  "data": {
    "linkId": 482,
    "range": "30d",
    "from": "2026-08-23T00:00:00.000Z",
    "to": "2026-09-22T00:00:00.000Z",
    "granularity": "day",
    "totals": {
      "clicks": 12483, "humans": 11204, "unique": 8851, "repeated": 2353, "bots": 1279,
      "previousClicks": 10560, "changePct": 18.2
    },
    "series": [
      { "start": "2026-08-23T00:00:00.000Z", "humans": 312, "unique": 247, "repeated": 65, "bots": 41 },
      …
    ],
    "breakdowns": {
      "countries": [ { "value": "DE", "label": "Germany", "clicks": 3914, "share": 34.9 }, … ],
      "referrers": [ { "value": "(direct)", "label": "Direct / none", "clicks": 4301, "share": 38.4 }, … ],
      "devices":   [ { "value": "iPhone", "label": "iPhone", "clicks": 5120, "share": 45.7 }, … ]
    },
    "recent": [
      { "at": "2026-09-21T14:42:07.000Z", "country": "DE", "countryName": "Germany", "device": "iPhone", "referrer": "newsletter.acme.com", "repeated": false }
    ]
  }
}

Click totals for up to 100 links at once — the numbers in the dashboard's links table. Lifetime totals unless you pass a range.

curl "https://my.vitravia.app/api/v1/analytics/clicks?ids=482,483&range=7d" -H "Authorization: Bearer $VITRAVIA_API_KEY"

{
  "data": {
    "range": "7d",
    "from": "2026-09-15T00:00:00.000Z",
    "to": "2026-09-22T00:00:00.000Z",
    "links": [ { "linkId": 482, "clicks": 3120 }, { "linkId": 483, "clicks": 0 } ]
  }
}

Clicks over time, split into unique visits, repeated visits and bots, with totals and the change against the period before. For a set, uniqueness is still per link: a visitor who opens two links in a tag counts once on each.

Weeks start on Monday and months on the 1st, in UTC — the same weeks whatever window you ask for, so they compare from one request to the next. The first and last can therefore reach outside the window; those are marked partial, and count only the days inside it. interval is echoed: ask for hours over a window whose hourly detail has been compacted away and you get days, and the response says so.

curl "https://my.vitravia.app/api/v1/analytics/timeline?tag=7&range=custom&from=2026-01-01&to=2026-06-30&interval=month" \
  -H "Authorization: Bearer $VITRAVIA_API_KEY"

{
  "data": {
    "scope": { "type": "tag", "id": 7, "name": "spring", "links": 437 },
    "range": "custom",
    "from": "2026-01-01T00:00:00.000Z",
    "to": "2026-07-01T00:00:00.000Z",
    "granularity": "day",
    "interval": "month",
    "totals": {
      "clicks": 91204, "humans": 84110, "unique": 70412, "repeated": 13698, "bots": 7094,
      "previousClicks": 80112, "changePct": 13.8
    },
    "series": [
      {
        "start": "2026-01-01T00:00:00.000Z", "end": "2026-02-01T00:00:00.000Z",
        "humans": 12840, "unique": 10702, "repeated": 2138, "bots": 1033, "partial": false
      },
      …
    ]
  }
}

One dimension, ranked: where the clicks came from, or on what.

share is a percentage of all clicks in totals, which are exact. coverage is how much of that the rows returned account for — under 100 only when limit cut the list, since the long tail is always there as (other).

Over a set, country and referrer rankings are approximate, and approximate says so. Each link keeps its own top values and folds the rest into (other) before a set is summed, so a value that was never near the top of any one link cannot appear as a row of its own, however much it adds up to across them. Devices, and any ranking for a single link, are exact.

curl "https://my.vitravia.app/api/v1/analytics/breakdown?domain=go.acme.com&by=referrer&range=30d&limit=3" \
  -H "Authorization: Bearer $VITRAVIA_API_KEY"

{
  "data": {
    "scope": { "type": "domain", "id": 3, "name": "go.acme.com", "links": 1204 },
    "range": "30d",
    "from": "2026-08-27T00:00:00.000Z",
    "to": "2026-09-26T00:00:00.000Z",
    "granularity": "day",
    "by": "referrer",
    "totals": { "clicks": 48210, "humans": 45002, "bots": 3208 },
    "approximate": true,
    "coverage": 71.6,
    "values": [
      { "value": "(direct)", "label": "Direct / none", "clicks": 20114, "share": 41.7 },
      { "value": "newsletter.acme.com", "label": "newsletter.acme.com", "clicks": 9870, "share": 20.5 },
      { "value": "(other)", "label": "Other", "clicks": 4530, "share": 9.4 }
    ]
  }
}