Smart Links

Create a link

curl -X POST https://api.subscriby.net/v1/projects/7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13/links \
  -H "Authorization: Bearer sbt_..." \
  -H "Idempotency-Key: 6b1f0d2e-9c3a-4e8b-b2d1-7a9c5e3f1d04" \
  -H "Content-Type: application/json" \
  -d '{"name":"YouTube description","slug":"youtube","destination":"plan","plan_id":"0c9d8e7f-6a5b-4c3d-8e2f-1a2b3c4d5e6f"}'

Answers 201 with the new link, its code minted and its three addresses built. destination is portal (the portal home), plan (the checkout of one plan, which needs plan_id) or bot (the project's bot; the portal home when no bot is connected). expires_at, in the future, stops the link counting after that moment.

The slug is lowercased before it is stored and checked, so Promo when promo exists is 422 VALIDATION_FAILED, not a second link; go, embed, portal, bot, direct, new and edit are reserved. Emits link.created.

post/v1/projects/{project}/links

Request

  • Base URL: https://api.subscriby.net
  • URL: https://api.subscriby.net/v1/projects/{project}/links
  • Auth: HTTP bearer

Path parameters

projectstring uuid required

The project, resolved by the route binder.

Headers

Idempotency-Keystring uuid required

A key unique to this operation, such as a fresh UUID. The same key replays the original 2xx response for 24 hours (with Idempotent-Replay: true), so a retry after a timeout never repeats the write; the same key with a different body is refused with 409.

Request body

namestring required

A creator-facing label, 2 to 120 characters, never shown to visitors; such as YouTube description.

slugstring required

The address segment after /go/: 2 to 32 letters, digits and hyphens, lowercased before it is stored and checked. Unique within the project; go, embed, portal, bot, direct, new and edit are reserved. Such as youtube.

destination'portal' | 'plan' | 'bot' required

Where a Smart Link sends the person who follows it. The destination decides the redirect and the bot payload: the portal's plan list, the checkout of one plan, or a conversation with the project's bot. The click and the attribution are recorded the same way whichever it is, so a creator can move a link between destinations without losing its figures.

plan_idstring nullable

The plan a plan destination opens; one of this project's plans. Refused as meaningless on the other destinations.

expires_atstring date-time nullable

When the link stops counting and crediting, ISO 8601, in the future. Omit for never; the address keeps landing on the portal home after it.

Response

The new link, 201.

Example response

{
  "data": {
    "id": "1e2a4c6b-3d5f-4a7b-9c1d-2e3f4a5b6c7d",
    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
    "name": "YouTube description",
    "slug": "youtube",
    "code": "TUBE234",
    "destination": {
      "type": "plan",
      "plan_id": "0c9d8e7f-6a5b-4c3d-8e2f-1a2b3c4d5e6f",
      "plan_name": "Premium"
    },
    "urls": {
      "web": "https://my.subscriby.net/research-premium/go/youtube",
      "bot": "https://t.me/ResearchPremiumBot?start=via_TUBE234",
      "embed": "https://my.subscriby.net/research-premium/embed/plans?via=TUBE234"
    },
    "state": "live",
    "clicks": {
      "total": 42,
      "last_at": "2026-10-10T08:00:00+00:00"
    },
    "created_at": "2026-10-01T09:00:00+00:00",
    "updated_at": "2026-10-10T08:00:00+00:00"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.