API reference

← Thylink developer documentation

Thylink API Documentation

Overview

Thylink exposes a RESTful JSON API for managing user profiles, links, and events. All endpoints live under the /api prefix.

Base URL: https://thyl.ink/api

Authentication

Thylink uses Laravel Sanctum bearer tokens for authentication.

Obtaining a Token

Authenticate via POST /api/auth/login and include the returned token in subsequent requests:

Authorization: Bearer {token}

Rate Limiting

Route Group Limit
Public (/auth, /sso) 10 req/min
Protected (all others) 100 req/min

Public Endpoints

Register

Create a new user account and receive an API token.

POST /api/auth/register
Field Type Required Description
name string ✅ Full name (max 255)
email string ✅ Unique email
username string ✅ Unique, alphanumeric + dashes
password string ✅ Min 8 characters
service_name string ✅ Token label (e.g. "My App")

Response 201:

{
  "message": "User registered successfully",
  "user": { ... },
  "token": "1|abc123..."
}

Login

Authenticate and receive a new API token.

POST /api/auth/login
Field Type Required Description
email string ✅ Account email
password string ✅ Account password
service_name string ✅ Token label (e.g. "WordPress Plugin")

Response 200:

{
  "message": "Login successful",
  "user": { ... },
  "token": "2|xyz789..."
}

Response 422 (invalid credentials):

{
  "message": "The provided credentials are incorrect.",
  "errors": { "email": ["..."] }
}

SSO Token

Create or find a user via SSO and return a token (30-day expiry).

POST /api/auth/sso/token
Field Type Required Description
email string ✅ User email
name string ✅ User name
username string ✅ Desired username (auto-deduped)
service_name string ✅ Token label
service_user_id string ✅ External user ID
language string ❌ en, es, fr, pt

Protected Endpoints

All endpoints below require Authorization: Bearer {token}.

User Management

Get Profile

GET /api/user/profile

Response 200:

{
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "[email protected]",
    "username": "johndoe",
    "bio": "Hello world",
    "website": "https://example.com",
    "profile_picture_url": "https://...",
    "show_email": true,
    "is_premium": false,
    "language": "en",
    "profile_url": "https://thyl.ink/johndoe",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z"
  }
}

Update Profile

PUT /api/user/profile
Field Type Required Description
name string ❌ Full name
bio string ❌ Bio text (max 500)
website url ❌ Website URL
external_profile_picture_url url ❌ Avatar URL
show_email boolean ❌ Show email on profile
language string ❌ en, es, fr, pt

Delete Account

DELETE /api/user/account

Permanently deletes the user, all tokens, links, videos, and customization.

Profile Management

Create Profile

POST /api/profiles
Field Type Required Description
name string ✅ Full name
email string ✅ Unique email
username string ✅ Unique username (alpha_dash)
bio string ❌ Bio (max 500)
website url ❌ Website URL
external_profile_picture_url url ❌ Avatar URL
show_email boolean ❌ Show email publicly
language string ❌ en, es, fr, pt

Response 201: user object + profile_url.

Get Profile

GET /api/profiles/{username}

Returns user data with all relationships: social_links, custom_links, youtube_videos, customization.

Update Profile

PUT /api/profiles/{username}

Same fields as Create (all optional).

Delete Profile

DELETE /api/profiles/{username}

Profile Customization

Get Customization

GET /api/profiles/{username}/customization

Update Customization

PUT /api/profiles/{username}/customization
Field Type Description
theme string Theme name (max 50)
primary_color string Hex color, e.g. #3b82f6
accent_color string Hex color
text_color string Hex color
background_style string Background style
layout_style string links or grid
card_style string Card style variant
show_shadows boolean Enable shadows
show_borders boolean Enable borders
font_style string Font family
heading_size string Heading size variant
button_style string rounded, square, or pill
button_variant string filled, outline, or ghost
enable_animations boolean Enable animations
enable_hover_effects boolean Enable hover effects

Social Links

List Social Links

GET /api/profiles/{username}/links/social

Add Social Link

POST /api/profiles/{username}/links/social
Field Type Required Description
platform string ✅ Platform name (max 50)
url url ✅ Profile URL
sort_order integer ❌ Display order

Update Social Link

PUT /api/profiles/{username}/links/social/{id}

Same fields as Add (all optional).

Delete Social Link

DELETE /api/profiles/{username}/links/social/{id}

Custom Links

List Custom Links

GET /api/profiles/{username}/links/custom

Add Custom Link

POST /api/profiles/{username}/links/custom
Field Type Required Description
title string ✅ Link title (max 255)
url url ✅ Destination URL
description string ❌ Description (max 500)
external_image_url url ❌ Thumbnail URL
is_active boolean ❌ Visible on profile (default true)
sort_order integer ❌ Display order

Update Custom Link

PUT /api/profiles/{username}/links/custom/{id}

Delete Custom Link

DELETE /api/profiles/{username}/links/custom/{id}

YouTube Videos

List Videos

GET /api/profiles/{username}/links/youtube

Add Video

POST /api/profiles/{username}/links/youtube
Field Type Required Description
video_id string ✅ YouTube video ID
title string ❌ Video title
is_active boolean ❌ Visible on profile (default true)

Update Video

PUT /api/profiles/{username}/links/youtube/{id}

Delete Video

DELETE /api/profiles/{username}/links/youtube/{id}

Events

List Upcoming Events

Returns the authenticated user's upcoming published events.

GET /api/events
Query Param Type Default Description
limit integer 10 Max events to return (≤ 50)

Response 200:

{
  "events": [
    {
      "id": 1,
      "title": "Concert in Madrid",
      "description": "Live music event",
      "location": "Madrid, Spain",
      "event_url": "https://tickets.example.com",
      "starts_at": "2026-04-15T20:00:00+00:00",
      "ends_at": "2026-04-15T23:00:00+00:00"
    }
  ],
  "total": 12
}

Analytics

Get Profile Stats

GET /api/analytics/profiles/{username}/stats

Response 200:

{
  "stats": {
    "profile_views": 0,
    "link_clicks": 0,
    "social_links_count": 5,
    "custom_links_count": 3,
    "youtube_videos_count": 2,
    "created_at": "2026-01-01T00:00:00Z"
  }
}

Get Profile Clicks

GET /api/analytics/profiles/{username}/clicks

Token Management

List Tokens

GET /api/tokens

Returns all active tokens for the authenticated user.

Create Token

POST /api/tokens
Field Type Required Description
name string ✅ Token label (max 255)
abilities string[] ❌ Token abilities (default ["*"])
expires_at datetime ❌ Expiration date (must be future)

Revoke Token

DELETE /api/tokens/{id}

SSO (External Services)

These endpoints require a service token header for inter-service authentication.

Authenticate

POST /api/sso/authenticate

Creates or updates a user from an external service and returns an access token.

Validate Token

POST /api/sso/token/validate

Validates an existing Sanctum token.

Create User

POST /api/sso/user/create

Creates a new user for an external service.

Sync User

POST /api/sso/user/sync

Syncs user data from an external service (updates name, bio, avatar, links, etc.).

Error Responses

All endpoints return consistent error responses:

Validation Error 422

{
  "message": "Validation failed",
  "errors": {
    "field_name": ["Error message"]
  }
}

Not Found 404

{
  "message": "Profile not found"
}

Unauthorized 401

{
  "message": "Unauthenticated."
}