Initial

main.py

@@ -0,0 +1,206 @@
+import gradio as gr
+import requests
+import json
+
+# Zu.lk API Base URL
+API_BASE_URL = "https://api.zu.lk"
+
+def parse_auth_header(auth_header):
+    """Parse authorization header to extract API key and secret"""
+    if not auth_header or auth_header.strip() == "":
+        return None, None
+    
+    # Format: "Bearer OfNJsl3lmt:$2b$10$qf2ZMINlvw"
+    try:
+        # Split by space and get the second part (after "Bearer ")
+        parts = auth_header.strip().split(" ", 1)
+        if len(parts) != 2 or parts[0] != "Bearer":
+            return None, None
+        
+        # Split the credentials by colon
+        credentials = parts[1]
+        api_key, api_secret = credentials.split(":", 1)
+        return api_key, api_secret
+    except ValueError:
+        return None, None
+
+def make_api_request(endpoint, method="GET", data=None, api_key=None, api_secret=None):
+    """Make authenticated request to Zu.lk API"""
+    if not api_key or not api_secret:
+        return {"error": "Invalid authentication credentials"}
+    
+    headers = {
+        "X-API-KEY": api_key,
+        "X-API-Secret": api_secret,
+        "Content-Type": "application/json"
+    }
+    
+    url = f"{API_BASE_URL}{endpoint}"
+    
+    try:
+        if method == "GET":
+            response = requests.get(url, headers=headers)
+        elif method == "POST":
+            response = requests.post(url, headers=headers, json=data)
+        elif method == "PUT":
+            response = requests.put(url, headers=headers, json=data)
+        elif method == "DELETE":
+            response = requests.delete(url, headers=headers)
+        else:
+            return {"error": f"Unsupported method: {method}"}
+        
+        return response.json()
+    except requests.exceptions.RequestException as e:
+        return {"error": f"Request failed: {str(e)}"}
+    except json.JSONDecodeError:
+        return {"error": "Invalid JSON response"}
+
+def get_organizations(request: gr.Request):
+    """Get user organizations"""
+    api_key, api_secret = parse_auth_header(request.headers.get('authorization', ''))
+    
+    if not api_key or not api_secret:
+        return "Error: Authorization is required (format: Bearer api_key:api_secret)"
+    
+    result = make_api_request("/v1/organizations", api_key=api_key, api_secret=api_secret)
+    return json.dumps(result, indent=2)
+
+def create_link(org_id, url, custom_key, length, request: gr.Request):
+    """Create a new short link"""
+    api_key, api_secret = parse_auth_header(request.headers.get('authorization', ''))
+    
+    if not api_key or not api_secret:
+        return "Error: Authorization is required (format: Bearer api_key:api_secret)"
+    
+    if not org_id or not url:
+        return "Error: Organization ID and URL are required"
+    
+    data = {"url": url}
+    if custom_key:
+        data["key"] = custom_key
+    if length and length > 0:
+        data["length"] = length
+    
+    result = make_api_request(f"/v1/organizations/{org_id}/links", method="POST", 
+                            data=data, api_key=api_key, api_secret=api_secret)
+    return json.dumps(result, indent=2)
+
+def get_org_links(org_id, request: gr.Request):
+    """Get all links for an organization"""
+    api_key, api_secret = parse_auth_header(request.headers.get('authorization', ''))
+    
+    if not api_key or not api_secret:
+        return "Error: Authorization is required (format: Bearer api_key:api_secret)"
+    
+    if not org_id:
+        return "Error: Organization ID is required"
+    
+    result = make_api_request(f"/v1/organizations/{org_id}/links", 
+                            api_key=api_key, api_secret=api_secret)
+    return json.dumps(result, indent=2)
+
+def get_analytics(org_id, date_from, date_to, interval, request: gr.Request):
+    """Get organization analytics"""
+    api_key, api_secret = parse_auth_header(request.headers.get('authorization', ''))
+    
+    if not api_key or not api_secret:
+        return "Error: Authorization is required (format: Bearer api_key:api_secret)"
+    
+    if not org_id:
+        return "Error: Organization ID is required"
+    
+    params = []
+    if date_from:
+        params.append(f"date_from={date_from}")
+    if date_to:
+        params.append(f"date_to={date_to}")
+    if interval:
+        params.append(f"interval={interval}")
+    
+    query_string = "&".join(params)
+    endpoint = f"/v1/organizations/{org_id}/analytics/clicks"
+    if query_string:
+        endpoint += f"?{query_string}"
+    
+    result = make_api_request(endpoint, api_key=api_key, api_secret=api_secret)
+    return json.dumps(result, indent=2)
+
+def update_link(org_id, link_id, new_url, new_key, request: gr.Request):
+    """Update an existing link"""
+    api_key, api_secret = parse_auth_header(request.headers.get('authorization', ''))
+    
+    if not api_key or not api_secret:
+        return "Error: Authorization is required (format: Bearer api_key:api_secret)"
+    
+    if not org_id or not link_id or not new_url or not new_key:
+        return "Error: Organization ID, Link ID, URL, and Key are required"
+    
+    data = {"url": new_url, "key": new_key}
+    
+    result = make_api_request(f"/v1/organizations/{org_id}/links/{link_id}", 
+                            method="PUT", data=data, api_key=api_key, api_secret=api_secret)
+    return json.dumps(result, indent=2)
+
+# Create Gradio interface with tabs
+with gr.Blocks(title="Zu.lk API Client") as demo:
+    gr.Markdown("# Zu.lk API Client")
+    gr.Markdown("Authorization format: `Bearer api_key:api_secret`")
+    
+    with gr.Tab("Organizations"):
+        with gr.Row():
+            org_btn = gr.Button("Get My Organizations")
+            org_output = gr.Textbox(label="Organizations", lines=10)
+        
+        org_btn.click(get_organizations, outputs=org_output)
+    
+    with gr.Tab("Create Link"):
+        with gr.Column():
+            create_org_id = gr.Textbox(label="Organization ID", placeholder="1")
+            create_url = gr.Textbox(label="URL to Shorten", placeholder="https://example.com")
+            create_key = gr.Textbox(label="Custom Key (optional)", placeholder="my-link")
+            create_length = gr.Number(label="Key Length (3-10)", value=6, minimum=3, maximum=10)
+            create_btn = gr.Button("Create Link")
+            create_output = gr.Textbox(label="Result", lines=8)
+        
+        create_btn.click(create_link, 
+                        inputs=[create_org_id, create_url, create_key, create_length],
+                        outputs=create_output)
+    
+    with gr.Tab("Manage Links"):
+        with gr.Column():
+            links_org_id = gr.Textbox(label="Organization ID", placeholder="1")
+            get_links_btn = gr.Button("Get All Links")
+            links_output = gr.Textbox(label="Links", lines=10)
+        
+        get_links_btn.click(get_org_links, 
+                           inputs=[links_org_id],
+                           outputs=links_output)
+    
+    with gr.Tab("Update Link"):
+        with gr.Column():
+            update_org_id = gr.Textbox(label="Organization ID", placeholder="1")
+            update_link_id = gr.Textbox(label="Link ID", placeholder="1")
+            update_url = gr.Textbox(label="New URL", placeholder="https://updated-example.com")
+            update_key = gr.Textbox(label="New Key", placeholder="updated-key")
+            update_btn = gr.Button("Update Link")
+            update_output = gr.Textbox(label="Result", lines=8)
+        
+        update_btn.click(update_link,
+                        inputs=[update_org_id, update_link_id, update_url, update_key],
+                        outputs=update_output)
+    
+    with gr.Tab("Analytics"):
+        with gr.Column():
+            analytics_org_id = gr.Textbox(label="Organization ID", placeholder="1")
+            analytics_from = gr.Textbox(label="Date From (optional)", placeholder="-7d")
+            analytics_to = gr.Textbox(label="Date To (optional)", placeholder="today")
+            analytics_interval = gr.Textbox(label="Interval (optional)", placeholder="day")
+            analytics_btn = gr.Button("Get Analytics")
+            analytics_output = gr.Textbox(label="Analytics", lines=12)
+        
+        analytics_btn.click(get_analytics,
+                           inputs=[analytics_org_id, analytics_from, analytics_to, analytics_interval],
+                           outputs=analytics_output)
+
+if __name__ == "__main__":
+    demo.launch(mcp_server=True, share=True)

zulk-api.yaml

@@ -0,0 +1,984 @@
+openapi: 3.0.0
+info:
+  version: 1.0.0
+  title: Zulk API
+  description: URL shortener API for Zulk platform
+servers:
+  - url: https://api.zu.lk
+    description: Production server
+  - url: http://localhost:8787
+    description: Development server
+tags:
+  - name: Authentication
+    description: 🔐 OAuth endpoints for web app authentication (no API key required)
+  - name: API v1 - Users
+    description: 👥 User management endpoints (requires API key)
+  - name: API v1 - Organizations
+    description: 🏢 Organization management endpoints (requires API key)
+  - name: API v1 - Links
+    description: 🔗 URL shortening endpoints (requires API key)
+  - name: API v1 - Analytics
+    description: 📊 Analytics and reporting endpoints (requires API key)
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: X-API-KEY
+      description: API Key for authentication
+    ApiSecretAuth:
+      type: apiKey
+      in: header
+      name: X-API-Secret
+      description: API Secret for authentication
+  schemas:
+    Link:
+      type: object
+      properties:
+        id:
+          type: string
+          example: "1"
+          description: Link ID
+        key:
+          type: string
+          example: abc123
+          description: Short link key
+        url:
+          type: string
+          format: uri
+          example: https://example.com
+          description: Original URL
+        created_at:
+          type: string
+          format: date-time
+          example: 2025-01-01T00:00:00Z
+          description: Creation timestamp
+        owner:
+          type: string
+          example: org123
+          description: Organization ID that owns this link
+    CreateLink:
+      type: object
+      required:
+        - url
+      properties:
+        key:
+          type: string
+          example: custom-key
+          description: Custom short key (optional)
+        url:
+          type: string
+          format: uri
+          example: https://example.com
+          description: URL to shorten
+        length:
+          type: integer
+          minimum: 3
+          maximum: 10
+          example: 6
+          description: "Length of generated key (3-10, default: 6)"
+    CreateLinkResponse:
+      type: object
+      properties:
+        message:
+          type: string
+          example: Record added successfully
+        created_at:
+          type: string
+          format: date-time
+          example: 2025-01-01T00:00:00Z
+        shortLink:
+          type: string
+          example: https://zu.lk/abc123
+        key:
+          type: string
+          example: abc123
+        url:
+          type: string
+          format: uri
+          example: https://example.com
+        length:
+          type: integer
+          example: 6
+    Error:
+      type: object
+      properties:
+        error:
+          type: string
+          example: Error message
+          description: Error message
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+          example: "123"
+          description: User ID
+        name:
+          type: string
+          example: John Doe
+          description: User name
+        age:
+          type: integer
+          example: 42
+          description: User age
+    AuthUser:
+      type: object
+      properties:
+        email:
+          type: string
+          format: email
+          example: user@example.com
+          description: User email (lowercased)
+        user:
+          type: object
+          properties:
+            id:
+              type: string
+              example: "123456789"
+              description: Google user ID
+            name:
+              type: string
+              example: John Doe
+              description: User display name
+            email:
+              type: string
+              format: email
+              example: user@example.com
+              description: User email from Google
+            picture:
+              type: string
+              format: uri
+              example: https://lh3.googleusercontent.com/...
+              description: User profile picture URL
+          description: Google OAuth user data
+        token:
+          type: string
+          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+          description: JWT token
+        apiKey:
+          type: string
+          example: ak_1234567890abcdef
+          description: User API key
+        apiToken:
+          type: string
+          example: at_1234567890abcdef
+          description: User API token
+    Organization:
+      type: object
+      properties:
+        id:
+          type: number
+          example: 1
+          description: Organization ID
+        name:
+          type: string
+          example: Acme Corp
+          description: Organization name
+        role:
+          type: string
+          example: OWNER
+          description: User role in the organization
+    OrganizationMember:
+      type: object
+      properties:
+        id:
+          type: number
+          example: 123
+          description: User ID
+        name:
+          type: string
+          example: John Doe
+          description: User name
+        email:
+          type: string
+          format: email
+          example: john@example.com
+          description: User email
+        role:
+          type: string
+          enum:
+            - MANAGER
+            - ADMIN
+            - OWNER
+          example: MANAGER
+          description: User role in the organization
+    AddMemberRequest:
+      type: object
+      required:
+        - email
+      properties:
+        email:
+          type: string
+          format: email
+          example: newmember@example.com
+          description: Email of the user to add
+        role:
+          type: string
+          enum:
+            - MANAGER
+            - ADMIN
+            - OWNER
+          example: MANAGER
+          default: MANAGER
+          description: Role to assign to the new member
+    UpdateRoleRequest:
+      type: object
+      required:
+        - role
+      properties:
+        role:
+          type: string
+          enum:
+            - MANAGER
+            - ADMIN
+            - OWNER
+          example: ADMIN
+          description: New role for the member
+    AnalyticsResponse:
+      type: object
+      properties:
+        orgId:
+          type: string
+          example: "1"
+          description: Organization ID
+        analytics:
+          type: object
+          properties:
+            totalClicks:
+              type: number
+              example: 1250
+              description: Total click count
+            dateRange:
+              type: object
+              properties:
+                from:
+                  type: string
+                  example: -7d
+                  description: Start date of the range
+                to:
+                  type: string
+                  example: today
+                  description: End date of the range
+            interval:
+              type: string
+              example: day
+              description: Data interval
+            data:
+              type: array
+              items:
+                type: number
+              example:
+                - 120
+                - 150
+                - 89
+                - 200
+                - 180
+                - 145
+                - 220
+              description: Click data points
+            labels:
+              type: array
+              items:
+                type: string
+              example:
+                - 2025-08-09
+                - 2025-08-10
+                - 2025-08-11
+                - 2025-08-12
+                - 2025-08-13
+                - 2025-08-14
+                - 2025-08-15
+              description: Date labels for data points
+        generatedAt:
+          type: string
+          format: date-time
+          example: 2025-08-15T12:00:00Z
+          description: Timestamp when analytics were generated
+    UpdateLinkRequest:
+      type: object
+      required:
+        - url
+        - key
+      properties:
+        url:
+          type: string
+          format: uri
+          example: https://updated-example.com
+          description: Updated URL
+        key:
+          type: string
+          example: updated-key
+          description: Updated short key
+    CreateOrganization:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          example: Acme Corp
+          description: Organization name
+security:
+  - ApiKeyAuth: []
+    ApiSecretAuth: []
+paths:
+  /v1/organizations:
+    get:
+      summary: Get user organizations
+      description: Retrieve organizations that the authenticated user has access to
+      tags:
+        - API v1 - Organizations
+      security:
+        - ApiKeyAuth: []
+          ApiSecretAuth: []
+      responses:
+        "200":
+          description: Successfully retrieved user organizations
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Organization"
+        "401":
+          description: Unauthorized - Invalid API credentials
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+    post:
+      summary: Create a new organization
+      description: Create a new organization and assign the authenticated user as owner
+      tags:
+        - API v1 - Organizations
+      security:
+        - ApiKeyAuth: []
+          ApiSecretAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateOrganization"
+      responses:
+        "200":
+          description: Successfully created organization
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                    example: Organization created successfully
+                  id:
+                    type: number
+                    example: 1
+                    description: Organization ID
+                  name:
+                    type: string
+                    example: Acme Corp
+                    description: Organization name
+                  role:
+                    type: string
+                    example: OWNER
+                    description: User role in the organization
+        "400":
+          description: Bad request - Name is required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "401":
+          description: Unauthorized - Invalid API credentials
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "500":
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /v1/organizations/{orgId}/members:
+    get:
+      summary: Get organization members
+      description: Retrieve all members of a specific organization
+      tags:
+        - API v1 - Organizations
+      security:
+        - ApiKeyAuth: []
+          ApiSecretAuth: []
+      parameters:
+        - name: orgId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Organization ID
+          example: "1"
+      responses:
+        "200":
+          description: Successfully retrieved organization members
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  members:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/OrganizationMember"
+                  total:
+                    type: number
+                    example: 5
+                    description: Total number of members
+        "401":
+          description: Unauthorized - Invalid API credentials
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "403":
+          description: Access denied to this organization
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+    post:
+      summary: Add member to organization
+      description: Add a new member to an organization (requires ADMIN or OWNER role)
+      tags:
+        - API v1 - Organizations
+      security:
+        - ApiKeyAuth: []
+          ApiSecretAuth: []
+      parameters:
+        - name: orgId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Organization ID
+          example: "1"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AddMemberRequest"
+      responses:
+        "200":
+          description: Successfully added member to organization
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                    example: Member added successfully
+                  member:
+                    $ref: "#/components/schemas/OrganizationMember"
+        "400":
+          description: Bad request - Email is required or invalid role
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "401":
+          description: Unauthorized - Invalid API credentials
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "403":
+          description: Access denied - Requires ADMIN or OWNER role
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "404":
+          description: User not found - User must register first
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+              example:
+                error: User not found. User must register first.
+        "409":
+          description: Conflict - User is already a member
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "500":
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /v1/organizations/{orgId}/members/{memberId}/role:
+    patch:
+      summary: Update member role
+      description: Update the role of a specific member in an organization (requires
+        ADMIN or OWNER role)
+      tags:
+        - API v1 - Organizations
+      security:
+        - ApiKeyAuth: []
+          ApiSecretAuth: []
+      parameters:
+        - name: orgId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Organization ID
+          example: "1"
+        - name: memberId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Member ID
+          example: "123"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UpdateRoleRequest"
+      responses:
+        "200":
+          description: Successfully updated member role
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                    example: Member role updated successfully
+                  member:
+                    type: object
+                    properties:
+                      id:
+                        type: number
+                        example: 123
+                      name:
+                        type: string
+                        example: John Doe
+                      email:
+                        type: string
+                        example: john@example.com
+                      role:
+                        type: string
+                        example: ADMIN
+                      previousRole:
+                        type: string
+                        example: MANAGER
+        "400":
+          description: Bad request - Role is required or invalid
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "401":
+          description: Unauthorized - Invalid API credentials
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "403":
+          description: Access denied - Requires ADMIN or OWNER role, or cannot change own
+            role
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "404":
+          description: Member not found in this organization
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+              example:
+                error: Member not found in this organization
+        "500":
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /v1/organizations/{orgId}/members/{memberId}:
+    delete:
+      summary: Remove member from organization
+      description: Remove a member from an organization (requires ADMIN or OWNER
+        role). Cannot remove yourself or the current OWNER.
+      tags:
+        - API v1 - Organizations
+      security:
+        - ApiKeyAuth: []
+          ApiSecretAuth: []
+      parameters:
+        - name: orgId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Organization ID
+          example: "1"
+        - name: memberId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Member ID
+          example: "123"
+      responses:
+        "200":
+          description: Successfully removed member from organization
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                    example: Member removed successfully
+                  removedMember:
+                    $ref: "#/components/schemas/OrganizationMember"
+        "401":
+          description: Unauthorized - Invalid API credentials
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "403":
+          description: Access denied - Requires ADMIN or OWNER role, cannot remove
+            yourself, or cannot remove last OWNER
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "404":
+          description: Member not found in this organization
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+              example:
+                error: Member not found in this organization
+        "500":
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /v1/organizations/{orgId}/analytics/clicks:
+    get:
+      summary: Get organization click analytics
+      description: Retrieve click analytics data for an organization's links from PostHog
+      tags:
+        - API v1 - Analytics
+      security:
+        - ApiKeyAuth: []
+          ApiSecretAuth: []
+      parameters:
+        - name: orgId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Organization ID
+          example: "1"
+        - name: date_from
+          in: query
+          required: false
+          schema:
+            type: string
+          description: "Start date for analytics (default: -7d)"
+          example: -7d
+        - name: date_to
+          in: query
+          required: false
+          schema:
+            type: string
+          description: "End date for analytics (default: today)"
+          example: today
+        - name: interval
+          in: query
+          required: false
+          schema:
+            type: string
+          description: "Data interval (default: day)"
+          example: day
+      responses:
+        "200":
+          description: Successfully retrieved analytics data
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AnalyticsResponse"
+        "401":
+          description: Unauthorized - Invalid API credentials
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "403":
+          description: Access denied to this organization
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "500":
+          description: Internal server error - Failed to fetch analytics data
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /v1/organizations/{orgId}/links:
+    get:
+      summary: Get organization links
+      description: Retrieve all links for a specific organization
+      tags:
+        - API v1 - Links
+      security:
+        - ApiKeyAuth: []
+          ApiSecretAuth: []
+      parameters:
+        - name: orgId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Organization ID
+          example: "1"
+      responses:
+        "200":
+          description: Successfully retrieved organization links
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Link"
+        "401":
+          description: Unauthorized - Invalid API credentials
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "403":
+          description: Access denied to this organization
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+    post:
+      summary: Create a new link in organization
+      description: Create a new short link for the given URL in the specified organization
+      tags:
+        - API v1 - Links
+      security:
+        - ApiKeyAuth: []
+          ApiSecretAuth: []
+      parameters:
+        - name: orgId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Organization ID
+          example: "1"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateLink"
+      responses:
+        "200":
+          description: Successfully created short link
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CreateLinkResponse"
+        "401":
+          description: Unauthorized - Invalid API credentials
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "403":
+          description: Access denied to this organization
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "500":
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /v1/organizations/{orgId}/links/{id}:
+    get:
+      summary: Get a specific link from organization
+      description: Retrieve a specific link by ID from the specified organization
+      tags:
+        - API v1 - Links
+      security:
+        - ApiKeyAuth: []
+          ApiSecretAuth: []
+      parameters:
+        - name: orgId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Organization ID
+          example: "1"
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Link ID
+          example: "1"
+      responses:
+        "200":
+          description: Successfully retrieved link
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Link"
+        "401":
+          description: Unauthorized - Invalid API credentials
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "403":
+          description: Access denied to this organization
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "404":
+          description: Link not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+              example:
+                error: Link not found
+  /v1/organizations/{orgId}/links/{linkId}:
+    put:
+      summary: Update a link in organization
+      description: Update an existing short link for the specified organization
+      tags:
+        - API v1 - Links
+      security:
+        - ApiKeyAuth: []
+          ApiSecretAuth: []
+      parameters:
+        - name: orgId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Organization ID
+          example: "1"
+        - name: linkId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Link ID
+          example: "1"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UpdateLinkRequest"
+      responses:
+        "200":
+          description: Successfully updated link
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                    example: Link updated successfully
+                  id:
+                    type: string
+                    example: "1"
+                    description: Link ID
+                  key:
+                    type: string
+                    example: updated-key
+                    description: Updated short key
+                  url:
+                    type: string
+                    format: uri
+                    example: https://updated-example.com
+                    description: Updated URL
+                  shortLink:
+                    type: string
+                    example: https://zu.lk/updated-key
+                    description: Full short link URL
+                  updated_at:
+                    type: string
+                    format: date-time
+                    example: 2025-08-15T12:00:00Z
+                    description: Update timestamp
+                  previousKey:
+                    type: string
+                    example: old-key
+                    description: Previous short key
+        "400":
+          description: Bad request - URL and key are required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "401":
+          description: Unauthorized - Invalid API credentials
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "403":
+          description: Access denied to this organization
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "404":
+          description: Link not found in this organization
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+              example:
+                error: Link not found in this organization
+        "409":
+          description: Conflict - Key is already taken
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "500":
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"