API Documentation — go.ramola.app

Introduction

The go.ramola.app API allows you to programmatically create and manage deep links to mobile apps. All API endpoints use JSON for requests and responses.

Note: API access is available on Pro and Business plans. View pricing

Base URL

https://go.ramola.app/api/v1

Content Type

All requests should use Content-Type: application/json header.

Authentication

Authenticate using your JWT token in the Authorization header. You can obtain a token by logging in via the authentication endpoint.

Get Your Token

POST /api/v1/auth/login

{
  "email": "you@example.com",
  "password": "your-password"
}

Response:
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Using the Token

curl https://go.ramola.app/api/v1/links \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json"

Security: Never share your token publicly or commit it to version control. Treat it like a password.

Rate Limits

API rate limits vary by plan:

Plan	Requests per minute	Requests per day
Free	No API access	—
Starter	No API access	—
Pro	60	10,000
Business	300	Unlimited

Rate limit information is included in response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1640000000

Error Handling

The API uses conventional HTTP response codes:

Code	Meaning
`200`	Success
`201`	Created
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing token
`403`	Forbidden - Insufficient permissions
`404`	Not Found
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Error Response Format

{
  "success": false,
  "error": "Bad Request",
  "message": "Invalid destination URL",
  "statusCode": 400
}

Create Link

POST /api/v1/links

Create a new deep link.

Request Body

Field	Type	Required	Description
`projectId`	string (UUID)	Yes	Your project ID
`destinationUrl`	string (URL)	Yes	The URL to redirect to
`appName`	string	Yes	Target app (amazon, instagram, tiktok, etc.)
`title`	string	No	Link title for dashboard
`shortCode`	string	No	Custom short code (auto-generated if not provided)
`expiresAt`	string (ISO 8601)	No	Expiration date

Example Request

curl -X POST https://go.ramola.app/api/v1/links \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "123e4567-e89b-12d3-a456-426614174000",
    "destinationUrl": "https://www.amazon.com/dp/B08N5WRWNW",
    "appName": "amazon",
    "title": "My Product Link"
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "abc123",
    "short_code": "x7K9mP",
    "destination_url": "https://www.amazon.com/dp/B08N5WRWNW",
    "shortUrl": "https://go.ramola.app/x7K9mP",
    "qrCodeUrl": "https://go.ramola.app/api/v1/links/abc123/qr",
    "created_at": "2026-02-15T12:00:00Z"
  }
}

Get Link

GET /api/v1/links/:id

Retrieve details for a specific link.

Example Request

curl https://go.ramola.app/api/v1/links/abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

{
  "success": true,
  "data": {
    "id": "abc123",
    "short_code": "x7K9mP",
    "destination_url": "https://www.amazon.com/dp/B08N5WRWNW",
    "title": "My Product Link",
    "clicks": 1250,
    "created_at": "2026-02-15T12:00:00Z",
    "shortUrl": "https://go.ramola.app/x7K9mP"
  }
}

List Links

GET /api/v1/links

List all links in your account with optional filters.

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (default: 20, max: 100)
`offset`	integer	Pagination offset (default: 0)
`projectId`	string (UUID)	Filter by project
`appName`	string	Filter by app (amazon, instagram, etc.)

Example Request

curl "https://go.ramola.app/api/v1/links?limit=50&appName=amazon" \
  -H "Authorization: Bearer YOUR_TOKEN"

Update Link

PATCH /api/v1/links/:id

Update a link's properties.

Request Body

All fields are optional. Only include fields you want to update.

Field	Type	Description
`title`	string	Update title
`destinationUrl`	string (URL)	Update destination
`isActive`	boolean	Enable/disable link

Example Request

curl -X PATCH https://go.ramola.app/api/v1/links/abc123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Product Link",
    "isActive": true
  }'

Delete Link

DELETE /api/v1/links/:id

Permanently delete a link.

Warning: This action cannot be undone. The short link will stop working immediately.

Example Request

curl -X DELETE https://go.ramola.app/api/v1/links/abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Analytics

GET /api/v1/links/:id/analytics

Get analytics data for a specific link.

Query Parameters

Parameter	Type	Description
`startDate`	string (ISO 8601)	Start date for analytics
`endDate`	string (ISO 8601)	End date for analytics
`interval`	string	Grouping interval (hour, day)

Example Response

{
  "success": true,
  "data": {
    "total_clicks": 1250,
    "by_device": {
      "ios": 450,
      "android": 620,
      "desktop": 180
    },
    "by_country": {
      "US": 800,
      "CA": 200,
      "UK": 150,
      "other": 100
    },
    "timeline": [
      {
        "date": "2026-02-15",
        "clicks": 125
      }
    ]
  }
}

Supported Apps

Valid values for the appName parameter:

App Name	Description
`amazon`	Amazon Shopping
`instagram`	Instagram
`tiktok`	TikTok
`youtube`	YouTube
`walmart`	Walmart
`target`	Target

Webhooks

Receive real-time notifications when events occur. Configure webhooks in your dashboard settings.

Available Events

link.created - A new link was created
link.clicked - A link was clicked
link.deleted - A link was deleted

Webhook Payload

{
  "event": "link.clicked",
  "timestamp": "2026-02-15T12:00:00Z",
  "data": {
    "link_id": "abc123",
    "short_code": "x7K9mP",
    "device": "ios",
    "country": "US"
  }
}

Coming Soon: Webhook functionality is currently in development.