Links API

List all short links

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

List all short links, with a token from the door.

curl -X GET 'https://zpe.vc/links/_/api/v1/links?range=24h' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

[
  {
    "id": 42,
    "url": "https://example.com/long-url",
    "label": "Marketing landing",
    "created_at": 0,
    "expires_at": null,
    "created_via": null,
    "created_by": "string",
    "slugs": [
      {
        "link_id": 0,
        "slug": "string",
        "is_custom": 0,
        "is_primary": 0,
        "click_count": 0,
        "created_at": 0,
        "disabled_at": null
      }
    ],
    "total_clicks": 137,
    "delta_pct": 0
  }
]

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Create a short link

Parameters

No parameters.

Request body application/json · optional

Responses

Example

Create a short link, with a token from the door.

curl -X POST 'https://zpe.vc/links/_/api/v1/links' \
  -H 'Authorization: Bearer $ZPE_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
  "url": "https://example.com",
  "label": "string",
  "slug_length": 0,
  "expires_at": 0,
  "allow_duplicate": false
}'

{
  "id": 42,
  "url": "https://example.com/long-url",
  "label": "Marketing landing",
  "created_at": 0,
  "expires_at": null,
  "created_via": null,
  "created_by": "string",
  "slugs": [
    {
      "link_id": 0,
      "slug": "string",
      "is_custom": 0,
      "is_primary": 0,
      "click_count": 0,
      "created_at": 0,
      "disabled_at": null
    }
  ],
  "total_clicks": 137,
  "delta_pct": 0
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Get a link with click stats

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Get a link with click stats, with a token from the door.

curl -X GET 'https://zpe.vc/links/_/api/v1/links/42?range=24h' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{
  "id": 42,
  "url": "https://example.com/long-url",
  "label": "Marketing landing",
  "created_at": 0,
  "expires_at": null,
  "created_via": null,
  "created_by": "string",
  "slugs": [
    {
      "link_id": 0,
      "slug": "string",
      "is_custom": 0,
      "is_primary": 0,
      "click_count": 0,
      "created_at": 0,
      "disabled_at": null
    }
  ],
  "total_clicks": 137,
  "delta_pct": 0
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Owner only. The identity behind the API key must be the link's `created_by`, otherwise the call is refused with 403.

Parameters

Request body application/json · optional

Responses

Example

Update a link's URL, label, or expiry, with a token from the door.

curl -X PUT 'https://zpe.vc/links/_/api/v1/links/42' \
  -H 'Authorization: Bearer $ZPE_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
  "url": "https://example.com",
  "label": null,
  "expires_at": null
}'

{
  "id": 42,
  "url": "https://example.com/long-url",
  "label": "Marketing landing",
  "created_at": 0,
  "expires_at": null,
  "created_via": null,
  "created_by": "string",
  "slugs": [
    {
      "link_id": 0,
      "slug": "string",
      "is_custom": 0,
      "is_primary": 0,
      "click_count": 0,
      "created_at": 0,
      "disabled_at": null
    }
  ],
  "total_clicks": 137,
  "delta_pct": 0
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Owner only, and only while the link has recorded zero clicks. Once any click exists the link is permanent and this call returns 400; disable it instead. Deleting removes the link, its slugs, and frees those slugs for reuse by anyone.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Delete a link permanently, with a token from the door.

curl -X DELETE 'https://zpe.vc/links/_/api/v1/links/42' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{
  "deleted": false
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Owner only. Stops every slug on the link from redirecting while keeping the link and its click history. This is the correct operation for a link that is already in circulation, and the only one available once the link has recorded a click.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Disable a link, with a token from the door.

curl -X POST 'https://zpe.vc/links/_/api/v1/links/42/disable' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{
  "id": 42,
  "url": "https://example.com/long-url",
  "label": "Marketing landing",
  "created_at": 0,
  "expires_at": null,
  "created_via": null,
  "created_by": "string",
  "slugs": [
    {
      "link_id": 0,
      "slug": "string",
      "is_custom": 0,
      "is_primary": 0,
      "click_count": 0,
      "created_at": 0,
      "disabled_at": null
    }
  ],
  "total_clicks": 137,
  "delta_pct": 0
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Owner only. Clears `expires_at` outright, including an expiry set at create or update, so the link resolves again and no longer expires.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Re-enable a disabled link, with a token from the door.

curl -X POST 'https://zpe.vc/links/_/api/v1/links/42/enable' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{
  "id": 42,
  "url": "https://example.com/long-url",
  "label": "Marketing landing",
  "created_at": 0,
  "expires_at": null,
  "created_via": null,
  "created_by": "string",
  "slugs": [
    {
      "link_id": 0,
      "slug": "string",
      "is_custom": 0,
      "is_primary": 0,
      "click_count": 0,
      "created_at": 0,
      "disabled_at": null
    }
  ],
  "total_clicks": 137,
  "delta_pct": 0
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Open to any authenticated caller with the `create` scope, including on a link owned by someone else. Adding a slug creates an additional address for the existing destination; it cannot change, disable or delete anything. Removing or disabling that slug afterwards is owner-gated.

Parameters

Request body application/json · optional

Responses

Example

Add a custom slug to a link, with a token from the door.

curl -X POST 'https://zpe.vc/links/_/api/v1/links/42/slugs' \
  -H 'Authorization: Bearer $ZPE_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
  "slug": "string"
}'

{
  "link_id": 0,
  "slug": "string",
  "is_custom": 0,
  "is_primary": 0,
  "click_count": 0,
  "created_at": 0,
  "disabled_at": null
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Owner of the parent link only. Custom slugs only: the system-generated slug cannot be disabled. The slug stops resolving and keeps its click history.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Disable a specific slug on a link, with a token from the door.

curl -X POST 'https://zpe.vc/links/_/api/v1/links/42/slugs/string/disable' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{
  "link_id": 0,
  "slug": "string",
  "is_custom": 0,
  "is_primary": 0,
  "click_count": 0,
  "created_at": 0,
  "disabled_at": null
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Owner of the parent link only.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Re-enable a disabled slug on a link, with a token from the door.

curl -X POST 'https://zpe.vc/links/_/api/v1/links/42/slugs/string/enable' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{
  "link_id": 0,
  "slug": "string",
  "is_custom": 0,
  "is_primary": 0,
  "click_count": 0,
  "created_at": 0,
  "disabled_at": null
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Owner of the parent link only, custom slugs only, and only while the slug has recorded zero clicks. Once any click exists the slug is permanent and this call returns 400; disable it instead.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Remove a custom slug from a link, with a token from the door.

curl -X DELETE 'https://zpe.vc/links/_/api/v1/links/42/slugs/string' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{
  "removed": false
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Get a QR code SVG for a link

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Get a QR code SVG for a link, with a token from the door.

curl -X GET 'https://zpe.vc/links/_/api/v1/links/42/qr?size=0&slug=string' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

"string"

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

List bundles a link belongs to

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

List bundles a link belongs to, with a token from the door.

curl -X GET 'https://zpe.vc/links/_/api/v1/links/42/bundles' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

[
  {
    "id": 0,
    "name": "string",
    "description": null,
    "icon": null,
    "accent": "orange",
    "archived_at": null,
    "created_via": null,
    "created_by": "string",
    "created_at": 0,
    "updated_at": 0
  }
]

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Get analytics for a link (defaults to all-time)

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Get analytics for a link (defaults to all-time), with a token from the door.

curl -X GET 'https://zpe.vc/links/_/api/v1/links/42/analytics?range=24h' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{
  "total_clicks": 0,
  "countries": [
    {
      "name": "string",
      "count": 0
    }
  ],
  "referrers": [
    {
      "name": "string",
      "count": 0
    }
  ],
  "referrer_hosts": [
    {
      "name": "string",
      "count": 0
    }
  ],
  "devices": [
    {
      "name": "string",
      "count": 0
    }
  ],
  "os": [
    {
      "name": "string",
      "count": 0
    }
  ],
  "browsers": [
    {
      "name": "string",
      "count": 0
    }
  ],
  "link_modes": [
    {
      "name": "string",
      "count": 0
    }
  ],
  "channels": [
    {
      "name": "string",
      "count": 0
    }
  ],
  "clicks_over_time": [
    {
      "date": "string",
      "count": 0
    }
  ],
  "slug_clicks": [
    {
      "slug": "string",
      "count": 0
    }
  ],
  "num_countries": 0,
  "num_referrers": 0,
  "num_referrer_hosts": 0,
  "num_os": 0,
  "num_browsers": 0
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Get click timeline for a link (defaults to all-time)

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Get click timeline for a link (defaults to all-time), with a token from the door.

curl -X GET 'https://zpe.vc/links/_/api/v1/links/42/timeline?range=24h' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{
  "range": "24h",
  "buckets": [
    {
      "label": "string",
      "count": 0
    }
  ],
  "summary": {
    "last_24h": 0,
    "last_7d": 0,
    "last_30d": 0,
    "last_90d": 0,
    "last_1y": 0
  }
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Page through a link's countries, sources, or domains breakdown

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Page through a link's countries, sources, or domains breakdown, with a token from the door.

curl -X GET 'https://zpe.vc/links/_/api/v1/links/42/breakdown?dimension=countries&limit=0&offset=<offset>&range=24h' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{
  "items": [
    {
      "name": "string",
      "count": 0
    }
  ],
  "total": 0
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Open to every authenticated key, whoever owns the link. Reads are not owner-scoped.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Look up a link by its slug, with a token from the door.

curl -X GET 'https://zpe.vc/links/_/api/v1/slugs/string' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{
  "id": 42,
  "url": "https://example.com/long-url",
  "label": "Marketing landing",
  "created_at": 0,
  "expires_at": null,
  "created_via": null,
  "created_by": "string",
  "slugs": [
    {
      "link_id": 0,
      "slug": "string",
      "is_custom": 0,
      "is_primary": 0,
      "click_count": 0,
      "created_at": 0,
      "disabled_at": null
    }
  ],
  "total_clicks": 137,
  "delta_pct": 0
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Every bundle on the deployment, not only the caller's. Reads are open across owners.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

List bundles, with a token from the door.

curl -X GET 'https://zpe.vc/links/_/api/v1/bundles?archived=1&range=24h' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

[
  {
    "id": 0,
    "name": "string",
    "description": null,
    "icon": null,
    "accent": "orange",
    "archived_at": null,
    "created_via": null,
    "created_by": "string",
    "created_at": 0,
    "updated_at": 0,
    "link_count": 0,
    "total_clicks": 0,
    "delta_pct": 0,
    "sparkline": [
      0
    ],
    "top_links": [
      {
        "slug": "string",
        "click_count": 0
      }
    ]
  }
]

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

The identity behind the API key becomes the bundle's owner and is the only one who can later change it.

Parameters

No parameters.

Request body application/json · optional

Responses

Example

Create a bundle, with a token from the door.

curl -X POST 'https://zpe.vc/links/_/api/v1/bundles' \
  -H 'Authorization: Bearer $ZPE_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
  "name": "string",
  "description": null,
  "icon": null,
  "accent": "orange"
}'

{
  "id": 0,
  "name": "string",
  "description": null,
  "icon": null,
  "accent": "orange",
  "archived_at": null,
  "created_via": null,
  "created_by": "string",
  "created_at": 0,
  "updated_at": 0
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Open to every authenticated key, whoever owns the bundle.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Get a bundle, with a token from the door.

curl -X GET 'https://zpe.vc/links/_/api/v1/bundles/42?range=24h' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{
  "id": 0,
  "name": "string",
  "description": null,
  "icon": null,
  "accent": "orange",
  "archived_at": null,
  "created_via": null,
  "created_by": "string",
  "created_at": 0,
  "updated_at": 0,
  "link_count": 0,
  "total_clicks": 0,
  "delta_pct": 0,
  "sparkline": [
    0
  ],
  "top_links": [
    {
      "slug": "string",
      "click_count": 0
    }
  ]
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Owner only. Refused with 403 for any other identity.

Parameters

Request body application/json · optional

Responses

Example

Update a bundle, with a token from the door.

curl -X PUT 'https://zpe.vc/links/_/api/v1/bundles/42' \
  -H 'Authorization: Bearer $ZPE_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
  "name": "string",
  "description": null,
  "icon": null,
  "accent": "orange"
}'

{
  "id": 0,
  "name": "string",
  "description": null,
  "icon": null,
  "accent": "orange",
  "archived_at": null,
  "created_via": null,
  "created_by": "string",
  "created_at": 0,
  "updated_at": 0
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Owner only. Unlike a link, a bundle carries no zero-click rule: a bundle is a grouping, not an address, so deleting one drops the memberships and leaves every member link and its click history in place. Archive instead when you only want it out of the default listing.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Delete a bundle permanently, with a token from the door.

curl -X DELETE 'https://zpe.vc/links/_/api/v1/bundles/42' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{
  "deleted": false
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Owner only. Hides the bundle from the default listing without deleting anything. Reversible through unarchive.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Archive a bundle, with a token from the door.

curl -X POST 'https://zpe.vc/links/_/api/v1/bundles/42/archive' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{
  "id": 0,
  "name": "string",
  "description": null,
  "icon": null,
  "accent": "orange",
  "archived_at": null,
  "created_via": null,
  "created_by": "string",
  "created_at": 0,
  "updated_at": 0
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Owner only. Returns an archived bundle to the default listing.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Unarchive a bundle, with a token from the door.

curl -X POST 'https://zpe.vc/links/_/api/v1/bundles/42/unarchive' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{
  "id": 0,
  "name": "string",
  "description": null,
  "icon": null,
  "accent": "orange",
  "archived_at": null,
  "created_via": null,
  "created_by": "string",
  "created_at": 0,
  "updated_at": 0
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Get bundle analytics. Defaults to all-time if no range given.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Get bundle analytics. Defaults to all-time if no range given., with a token from the door.

curl -X GET 'https://zpe.vc/links/_/api/v1/bundles/42/analytics?range=24h' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{
  "total_clicks": 0,
  "countries": [
    {
      "name": "string",
      "count": 0
    }
  ],
  "referrers": [
    {
      "name": "string",
      "count": 0
    }
  ],
  "referrer_hosts": [
    {
      "name": "string",
      "count": 0
    }
  ],
  "devices": [
    {
      "name": "string",
      "count": 0
    }
  ],
  "os": [
    {
      "name": "string",
      "count": 0
    }
  ],
  "browsers": [
    {
      "name": "string",
      "count": 0
    }
  ],
  "link_modes": [
    {
      "name": "string",
      "count": 0
    }
  ],
  "channels": [
    {
      "name": "string",
      "count": 0
    }
  ],
  "clicks_over_time": [
    {
      "date": "string",
      "count": 0
    }
  ],
  "slug_clicks": [
    {
      "slug": "string",
      "count": 0
    }
  ],
  "num_countries": 0,
  "num_referrers": 0,
  "num_referrer_hosts": 0,
  "num_os": 0,
  "num_browsers": 0
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Page through a bundle's countries, sources, or domains breakdown

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Page through a bundle's countries, sources, or domains breakdown, with a token from the door.

curl -X GET 'https://zpe.vc/links/_/api/v1/bundles/42/breakdown?dimension=countries&limit=0&offset=<offset>&range=24h' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{
  "items": [
    {
      "name": "string",
      "count": 0
    }
  ],
  "total": 0
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Open to every authenticated key, whoever owns the bundle or its links.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

List links in a bundle, with a token from the door.

curl -X GET 'https://zpe.vc/links/_/api/v1/bundles/42/links' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

[
  {
    "id": 42,
    "url": "https://example.com/long-url",
    "label": "Marketing landing",
    "created_at": 0,
    "expires_at": null,
    "created_via": null,
    "created_by": "string",
    "slugs": [
      {
        "link_id": 0,
        "slug": "string",
        "is_custom": 0,
        "is_primary": 0,
        "click_count": 0,
        "created_at": 0,
        "disabled_at": null
      }
    ],
    "total_clicks": 137,
    "delta_pct": 0
  }
]

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Open to any authenticated caller with the `create` scope: adding requires owning neither the bundle nor the link. Idempotent. Removing the link again is owner-gated.

Parameters

Request body application/json · optional

Responses

Example

Add a link to a bundle, with a token from the door.

curl -X POST 'https://zpe.vc/links/_/api/v1/bundles/42/links' \
  -H 'Authorization: Bearer $ZPE_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
  "link_id": 0
}'

{
  "added": false
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Bundle owner only, whoever owns the link. Owning the link does not grant removal from someone else's bundle. The link itself is not deleted.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Remove a link from a bundle, with a token from the door.

curl -X DELETE 'https://zpe.vc/links/_/api/v1/bundles/42/links/17' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{
  "removed": false
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Every name the key's owner holds that carries a page, with its blocks. An account holds at most five pages, so this is one page of results and takes no paging parameters.

Parameters

No parameters.

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

List the pages this key can write, with a token from the door.

curl -X GET 'https://zpe.vc/links/_/api/v1/pages' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

[
  {
    "name": "string",
    "headline": "string",
    "bio": "string",
    "email": null,
    "theme": "ink",
    "accent": "string",
    "created_at": 0,
    "updated_at": 0,
    "blocks": [
      {
        "id": 0,
        "name": "string",
        "position": 0,
        "kind": "link",
        "title": "string",
        "subtitle": null,
        "href": null,
        "app_id": null,
        "r2_key": null,
        "alt": null,
        "body": null,
        "is_first": false,
        "visible": false,
        "created_at": 0,
        "updated_at": 0
      }
    ]
  }
]

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

The page's fields and every block, in the order a visitor would see them, plus the report the editor draws: views, taps per block, the answers each question holds, the acts the page performs, and the countries and hosts the visits came from. Both doors read the report from one grouped read, so the JSON and the tab cannot disagree. Bots are stored and excluded from every count.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Read one page, and its numbers, with a token from the door.

curl -X GET 'https://zpe.vc/links/_/api/v1/pages/string' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{
  "name": "string",
  "headline": "string",
  "bio": "string",
  "email": null,
  "theme": "ink",
  "accent": "string",
  "created_at": 0,
  "updated_at": 0,
  "blocks": [
    {
      "id": 0,
      "name": "string",
      "position": 0,
      "kind": "link",
      "title": "string",
      "subtitle": null,
      "href": null,
      "app_id": null,
      "r2_key": null,
      "alt": null,
      "body": null,
      "is_first": false,
      "visible": false,
      "created_at": 0,
      "updated_at": 0
    }
  ],
  "report": {
    "views": 0,
    "taps": 0,
    "intents": 3,
    "acts": {
      "card": 0,
      "email": 0,
      "share": 0,
      "submit": 0
    },
    "blocks": [
      {
        "id": 7,
        "title": "Book a call",
        "taps": 4,
        "answers": 3,
        "on_page": false
      }
    ],
    "rules": [
      {
        "id": 3,
        "kind": "host",
        "value": "instagram.com",
        "taps": 5,
        "on_page": false
      }
    ],
    "countries": [
      {
        "value": "ID",
        "count": 12
      }
    ],
    "hosts": [
      {
        "value": "ID",
        "count": 12
      }
    ],
    "bot_views": 0
  }
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

The one line, the longer note, the address and the look. The first save creates the page row, which is what publishing requires.

Parameters

Request body application/json · optional

Responses

Example

Write a page's fields, with a token from the door.

curl -X PUT 'https://zpe.vc/links/_/api/v1/pages/string' \
  -H 'Authorization: Bearer $ZPE_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
  "headline": "string",
  "bio": "string",
  "email": null,
  "theme": "ink",
  "accent": "ember"
}'

{
  "name": "string",
  "headline": "string",
  "bio": "string",
  "email": null,
  "theme": "ink",
  "accent": "string",
  "created_at": 0,
  "updated_at": 0,
  "blocks": [
    {
      "id": 0,
      "name": "string",
      "position": 0,
      "kind": "link",
      "title": "string",
      "subtitle": null,
      "href": null,
      "app_id": null,
      "r2_key": null,
      "alt": null,
      "body": null,
      "is_first": false,
      "visible": false,
      "created_at": 0,
      "updated_at": 0
    }
  ]
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Every answer the page's questions collected in the last 90 days, newest first, each with the block it answers and that block's title as it reads now. The window and the bot rule are the report's own, so a block's `answers` figure and this list count the same rows. An answer whose block was since removed is still listed, with a null title: the answer outlives its question by design.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Read a page's answers, with a token from the door.

curl -X GET 'https://zpe.vc/links/_/api/v1/pages/string/submissions' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{
  "answers": [
    {
      "id": 12,
      "block_id": 7,
      "block_title": "Ask me anything",
      "value": "hello@example.test",
      "at": 0,
      "country": "TH"
    }
  ]
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

A page holds 12 blocks. The first ask is exclusive: adding a block with is_first clears whichever one held it.

Parameters

Request body application/json · optional

Responses

Example

Add a block, with a token from the door.

curl -X POST 'https://zpe.vc/links/_/api/v1/pages/string/blocks' \
  -H 'Authorization: Bearer $ZPE_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
  "kind": "link",
  "title": "string",
  "subtitle": "string",
  "href": "string",
  "app_id": "string",
  "field": "email",
  "label": "string",
  "consent": "string",
  "r2_key": "string",
  "alt": "string",
  "body": "string",
  "is_first": false,
  "visible": false
}'

{
  "id": 0,
  "name": "string",
  "position": 0,
  "kind": "link",
  "title": "string",
  "subtitle": null,
  "href": null,
  "app_id": null,
  "r2_key": null,
  "alt": null,
  "body": null,
  "is_first": false,
  "visible": false,
  "created_at": 0,
  "updated_at": 0
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Only the keys sent are written. The kind cannot change. Hiding the first ask clears it, because an ask nobody can see is not an ask.

Parameters

Request body application/json · optional

Responses

Example

Change one block, with a token from the door.

curl -X PATCH 'https://zpe.vc/links/_/api/v1/pages/string/blocks/{id}' \
  -H 'Authorization: Bearer $ZPE_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
  "kind": "link",
  "title": "string",
  "subtitle": "string",
  "href": "string",
  "app_id": "string",
  "field": "email",
  "label": "string",
  "consent": "string",
  "r2_key": "string",
  "alt": "string",
  "body": "string",
  "is_first": false,
  "visible": false
}'

{
  "id": 0,
  "name": "string",
  "position": 0,
  "kind": "link",
  "title": "string",
  "subtitle": null,
  "href": null,
  "app_id": null,
  "r2_key": null,
  "alt": null,
  "body": null,
  "is_first": false,
  "visible": false,
  "created_at": 0,
  "updated_at": 0
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

The taps a block earned are kept: the report says what happened, and a removed block does not un-happen it.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Remove one block, with a token from the door.

curl -X DELETE 'https://zpe.vc/links/_/api/v1/pages/string/blocks/{id}' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

The name starts answering at its address with no destination beside it. Refused when the page was never written or has nothing visible.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Publish a page, with a token from the door.

curl -X POST 'https://zpe.vc/links/_/api/v1/pages/string/publish' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{
  "name": "string",
  "state": "claimed",
  "published": false
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

The address stops answering and the page is left whole, so publishing again brings the same page back.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Unpublish a page, with a token from the door.

curl -X POST 'https://zpe.vc/links/_/api/v1/pages/string/unpublish' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{
  "name": "string",
  "state": "claimed",
  "published": false
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

**Public.** The form a stranger opens at `zpe.vc/links/new`: the markup, the caps and the script that posts the drop. No key and no session — this is the one address a person who has never heard of the door is sent to. Any other method on this path is the intake's own 404 page, not a second operation.

Parameters

No parameters.

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

The intake page, with a token from the door.

curl -X GET 'https://zpe.vc/links/new' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

"string"

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

**Public.** The page calls this once when the form first paints. The call writes the dwell anchor's row (a salted hash of the caller, and the first time it was seen) and answers the caps the page shows: the dwell floor, the per-hour send cap and the text cap. It reads nothing back and refuses nothing.

Parameters

No parameters.

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

The form was opened (the dwell anchor's row), with a token from the door.

curl -X GET 'https://zpe.vc/links/new/api/form' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

**Public.** The only write a stranger makes. The browser posts the form (multipart) and a script posts JSON; both reach the same fields and the same file walk. A browser is answered `303` to its receipt page; a script is answered `201` with `{receipt, status}`. A replayed drop under the dedupe window answers `201` with the SAME receipt and writes no second row. Every refusal (`413` cap, `429` per-address, `422` fields) is the app's `{ok:false, code, errors}` body.

Parameters

No parameters.

Request body multipart/form-data · required

The document declares no properties for this body.

Responses

Example

One drop: the answers and the files in one body, with a token from the door.

curl -X POST 'https://zpe.vc/links/new/api/submit' \
  -H 'Authorization: Bearer $ZPE_TOKEN' \
  -H 'content-type: application/json' \
  -d '{}'

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

**Public, with the receipt as the credential.** The receipt page's file picker posts here. The receipt names the build and nothing else authorises the write: a person holding the eight characters is the person the drop belongs to. A file already stored under the same digest is a duplicate and is not written twice.

Parameters

Request body multipart/form-data · required

The document declares no properties for this body.

Responses

Example

The receipt holder adds files after the drop, with a token from the door.

curl -X POST 'https://zpe.vc/links/new/api/string/files' \
  -H 'Authorization: Bearer $ZPE_TOKEN' \
  -H 'content-type: application/json' \
  -d '{}'

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

**Key.** The runner reads what the assembler wrote: the extracted content, the build's status and when it moved. Refused with `401` without an `Authorization: Bearer` account key granted `zpe-links`, and with `403` when the grant is read-only.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

The assembled object (key), with a token from the door.

curl -X GET 'https://zpe.vc/links/new/api/string/content' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

**Key.** The one write that puts the assembled object on the build. It is written once: a second write to a build that already holds content is refused rather than merged.

Parameters

Request body application/json · required

The document declares no properties for this body.

Responses

Example

The assembler writes the object, once (key), with a token from the door.

curl -X POST 'https://zpe.vc/links/new/api/string/content' \
  -H 'Authorization: Bearer $ZPE_TOKEN' \
  -H 'content-type: application/json' \
  -d '{}'

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

**Key.** Reads the draft that is held for this build: the subject and body, the recipient, the latest sign-off and every send attempt so far. A caller that only wants to see the words can stop here — nothing is sent by a read.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

The held message, its sign-off and its attempts (key), with a token from the door.

curl -X GET 'https://zpe.vc/links/new/api/string/message' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

**Key.** Writes the draft the sender will read. A second post to a build that already holds a message is refused: the draft is written once, and a correction is a new build rather than a quiet rewrite of words somebody may have signed.

Parameters

Request body application/json · required

The document declares no properties for this body.

Responses

Example

Write the held message for a row already read (key), with a token from the door.

curl -X POST 'https://zpe.vc/links/new/api/string/message' \
  -H 'Authorization: Bearer $ZPE_TOKEN' \
  -H 'content-type: application/json' \
  -d '{}'

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

**Key.** Records that a person read this exact draft, addressed to this exact recipient: the sign-off names the draft's hash, so a body that moved after the signature no longer matches it. `release` refuses without one.

Parameters

Request body application/json · required

The document declares no properties for this body.

Responses

Example

Record a sign-off naming the body and the recipient (key), with a token from the door.

curl -X POST 'https://zpe.vc/links/new/api/string/message/sign' \
  -H 'Authorization: Bearer $ZPE_TOKEN' \
  -H 'content-type: application/json' \
  -d '{}'

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

**Key.** The one operation in this app that sends mail. It refuses unless the held message carries a sign-off whose draft hash still matches, so a caller cannot post words nobody read. The refusal codes are the contract `tools/mail-release.mjs` turns into exit codes — `409` is 'nobody signed this', not 'the mail service refused it'.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

The app's only send (key, and refused without a sign-off), with a token from the door.

curl -X POST 'https://zpe.vc/links/new/api/string/release' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

**Public, with the receipt as the credential.** The receipt page: what was received, the files, the held message's state, the address box when the record holds no address, and the confirm link. A receipt nobody holds answers the same page at `404`, so the answer never says whether a receipt exists.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

The page the submitter waits on, with a token from the door.

curl -X GET 'https://zpe.vc/links/new/r/string' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

"string"

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

**Door.** Unreachable without the door's session: the receipt opens the record, and only a signed-in principal can become its owner — answered `401` with no session, and `503` when the door itself cannot be reached (which is not a refusal, because the person may well be signed in). A browser is sent back to the receipt page with `303`; a script is told `{ok:true, receipt, owner_principal}`. Only a published row nobody has kept can be claimed, once.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

Keep the published page, once, for the door's principal, with a token from the door.

curl -X POST 'https://zpe.vc/links/new/r/string/claim' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

**Public, with the receipt as the credential.** The person says where their link should go. This recomposes the held draft and writes nothing anybody can send: the message still waits for a read and a sign-off. A browser is sent back to the receipt page with `303`.

Parameters

Request body application/x-www-form-urlencoded · required

The document declares no properties for this body.

Responses

Example

The address the page asks for when the record holds none, with a token from the door.

curl -X POST 'https://zpe.vc/links/new/r/string/email' \
  -H 'Authorization: Bearer $ZPE_TOKEN' \
  -H 'content-type: application/json' \
  -d '{}'

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

**Public, with the receipt as the credential.** The page that lets the person fix a field before the press. It is a read: nothing is confirmed until the POST below.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

The correction page, with a token from the door.

curl -X GET 'https://zpe.vc/links/new/r/string/confirm' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

"string"

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

**Public, with the receipt as the credential.** The only act that moves a build to `confirmed`: the page's press, with the corrected fields. It answers `303` back to the receipt page, which is where the published address appears.

Parameters

Request body application/x-www-form-urlencoded · required

The document declares no properties for this body.

Responses

Example

The person's press, which is what confirms, with a token from the door.

curl -X POST 'https://zpe.vc/links/new/r/string/confirm' \
  -H 'Authorization: Bearer $ZPE_TOKEN' \
  -H 'content-type: application/json' \
  -d '{}'

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

**Public, with the receipt as the credential.** The bytes of one file on this build, streamed from R2 through the worker so the bucket is never public. The receipt and the file id must belong together: a file id from somebody else's build is not a row and answers `404`.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

One stored file, streamed through the worker, with a token from the door.

curl -X GET 'https://zpe.vc/links/new/r/string/f/00000000-0000-4000-8000-000000000000' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

"string"

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

**Public.** The product the intake exists for: the page a drop becomes after the press and the publish, at `zpe.vc/u/<name>`. No key and no session — this is the address the business prints. It answers at that mount only: measured 2026-11-06, `zpe.vc/u/<name>` is 200 and `zpe.vc/links/u/<name>` is 404, which is why this path item carries its own `servers`. A name that holds no live page answers the signpost's own `404`, never somebody else's page.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

The published page, with a token from the door.

curl -X GET 'https://zpe.vc/u/string' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

"string"

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

**Public.** The page's 'save my card' act at `zpe.vc/u/<name>/card.vcf`: the page's own name, headline, address and contact as `text/vcard`, built from the same row the page reads. The read records its row before it answers, so the operator can see the card was taken.

Parameters

Request body

None: this operation takes its arguments in the path and the query.

Responses

Example

The published page's card, as a vCard, with a token from the door.

curl -X GET 'https://zpe.vc/u/string/card.vcf' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

"string"

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.