Platform API

The Platform API allows you to programmatically manage your Detour resources and retrieve analytics data. All endpoints require authentication using a secret API key.

Authentication

All Platform API endpoints require authentication via Bearer token and application identification.

API Key Types

Detour provides two types of API keys:

Key Type	Purpose	Use Case
Publishable	Identify your app, used in SDKs	Client-side SDK implementations
Secret	Full platform management & administration	Server-side API calls, automation

Authentication Headers

Include the following headers in all API requests:

Authorization: Bearer <SECRET_API_KEY>
X-App-ID: <YOUR_APP_ID>

Example:

curl -X GET https://api.godetour.link/api/manage/short-links \
  -H "Authorization: Bearer 1234567890abc..." \
  -H "X-App-ID: your-app-id"

info

Secret keys must be stored securely on your server. Never expose them in client-side code or commit them to version control.

Endpoints

Short Links Management

GET /api/manage/short-links

Retrieve all short links for your app.

Authentication: Requires secret API key

Query Parameters: None

Response:

[
  {
    "id": "short_link_uuid",
    "hash": "abc123",
    "url": "https://acme-corp.godetour.link/abc123",
    "parameters": "{\"campaign\":\"summer_sale\"}",
    "name": "Summer Sale Campaign",
    "link_id": "link_uuid",
    "created_at": "2026-06-16T10:30:00.000Z"
  }
]

Status Codes:

200 OK — Successfully retrieved short links
401 Unauthorized — Invalid or missing API key
429 Too Many Requests — Rate limit exceeded
500 Internal Server Error — Server error

Example:

curl -X GET https://api.godetour.link/api/manage/short-links \
  -H "Authorization: Bearer a1b2c3d4e5f6..." \
  -H "X-App-ID: my-app"

POST /api/manage/short-links

Create a new short link for your app.

Authentication: Requires secret API key

Request Body:

{
  "parameters": "{\"campaign\":\"summer_sale\",\"utm_source\":\"email\"}",
  "name": "Summer Sale Email Campaign"
}

Required Fields:

parameters (string) — JSON string of custom parameters (cannot be empty)

Optional Fields:

name (string) — User-friendly name for the short link

Response:

{
  "id": "short_link_uuid",
  "hash": "abc123",
  "url": "https://acme-corp.godetour.link/abc123",
  "parameters": "{\"campaign\":\"summer_sale\",\"utm_source\":\"email\"}",
  "name": "Summer Sale Email Campaign",
  "link_id": "link_uuid",
  "created_at": "2026-06-16T10:35:00.000Z"
}

Status Codes:

201 Created — Short link successfully created
400 Bad Request — Invalid request body (missing required fields)
401 Unauthorized — Invalid or missing API key
402 Payment Required — Short link limit reached on free plan
404 Not Found — Link not found for this app
429 Too Many Requests — Rate limit exceeded
500 Internal Server Error — Server error

Plan Limits:

Plan	Short Links Limit
Free	50
Paid	Unlimited

Examples:

Create a short link:

curl -X POST https://api.godetour.link/api/manage/short-links \
  -H "Authorization: Bearer a1b2c3d4e5f6..." \
  -H "X-App-ID: my-app" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": "{\"campaign\":\"summer_sale\"}",
    "name": "Summer Sale"
  }'

PATCH /api/manage/short-links

Update an existing short link's parameters and name.

Authentication: Requires secret API key

Request Body:

{
  "id": "short_link_uuid",
  "parameters": "{\"campaign\":\"fall_sale\"}",
  "name": "Fall Sale Campaign"
}

Required Fields:

id (string) — UUID of the short link to update
parameters (string) — Updated JSON string of custom parameters

Optional Fields:

name (string) — Updated user-friendly name

Response:

{
  "id": "short_link_uuid",
  "hash": "abc123",
  "url": "https://acme-corp.godetour.link/abc123",
  "parameters": "{\"campaign\":\"fall_sale\"}",
  "name": "Fall Sale Campaign",
  "link_id": "link_uuid",
  "created_at": "2026-06-16T10:35:00.000Z"
}

Status Codes:

200 OK — Short link successfully updated
400 Bad Request — Invalid request body (missing required fields)
401 Unauthorized — Invalid or missing API key
404 Not Found — Short link not found
429 Too Many Requests — Rate limit exceeded
500 Internal Server Error — Server error

Example:

curl -X PATCH https://api.godetour.link/api/manage/short-links \
  -H "Authorization: Bearer a1b2c3d4e5f6..." \
  -H "X-App-ID: my-app" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "short_link_uuid",
    "parameters": "{\"campaign\":\"fall_sale\"}",
    "name": "Fall Sale Campaign"
  }'

Link Management

GET /api/manage/links

Retrieve the main link information for your app, including URL, redirect settings, and parameter configuration.

Authentication: Requires secret API key

Query Parameters: None

Response:

{
  "id": "link_uuid",
  "url": "https://example.com",
  "redirect_url": "https://fallback.example.com",
  "params_pass_strategy": "all",
  "specific_params": null,
  "created_at": "2026-06-16T10:00:00.000Z",
  "app_hash": "x9y8z7"
}

Fields:

id (string) — UUID of the link
url (string) — Primary redirect URL
redirect_url (string) — Fallback redirect URL
params_pass_strategy (string) — How parameters are passed: "all", "none", or "specific"
specific_params (array | null) — If set, only these parameters are passed through
created_at (string) — Link creation timestamp (ISO 8601)
app_hash (string) — Hash identifier used in short link URLs

Status Codes:

200 OK — Successfully retrieved link
401 Unauthorized — Invalid or missing API key
404 Not Found — Link not found for this app
429 Too Many Requests — Rate limit exceeded
500 Internal Server Error — Server error

Example:

curl -X GET https://api.godetour.link/api/manage/links \
  -H "Authorization: Bearer a1b2c3d4e5f6..." \
  -H "X-App-ID: my-app"

Analytics

GET /api/analytics/stats

Retrieve analytics data for your app with various export formats and filtering options.

Authentication: Requires secret API key

Query Parameters:

Parameter	Type	Required	Default	Description
`type`	string	Yes	—	Data type: `"overview"`, `"links"`, or `"events"`
`startDate`	string	Yes	—	Start of date range (ISO 8601, e.g., `2026-06-01T00:00:00Z`)
`endDate`	string	Yes	—	End of date range (ISO 8601, e.g., `2026-06-30T23:59:59Z`). Max range: 120 days
`format`	string	No	`json`	Export format: `"json"`, `"csv"` or `"xlsx"`
`platform`	string	No	`all`	Filter by platform: `"all"`, `"ios"`, or `"android"`
`linkId`	string	No	—	UUID of a specific link to scope the query. Defaults to the main app link (relevant for `"links"` and `"overview"` types; ignored for `"events"`)

Plan Requirements:

`type`	Required Plan
`overview`	Free
`links`	Paid
`events`	Paid

Status Codes:

200 OK — Analytics data successfully retrieved
400 Bad Request — Missing or invalid type parameter, or date range exceeds 120 days
401 Unauthorized — Invalid or missing API key
402 Payment Required — This data type requires a paid plan
429 Too Many Requests — Rate limit exceeded
500 Internal Server Error — Server error

Examples:

Get overview analytics:

curl -X GET "https://api.godetour.link/api/analytics/stats?type=overview&startDate=2026-06-01T00:00:00Z&endDate=2026-06-30T23:59:59Z" \
  -H "Authorization: Bearer a1b2c3d4e5f6..." \
  -H "X-App-ID: my-app"

Export link analytics as CSV (paid):

curl -X GET "https://api.godetour.link/api/analytics/stats?type=links&format=csv&startDate=2026-06-01T00:00:00Z&endDate=2026-06-30T23:59:59Z" \
  -H "Authorization: Bearer a1b2c3d4e5f6..." \
  -H "X-App-ID: my-app" \
  -o analytics.csv

Filter by platform:

curl -X GET "https://api.godetour.link/api/analytics/stats?type=events&platform=ios&startDate=2026-06-01T00:00:00Z&endDate=2026-06-30T23:59:59Z" \
  -H "Authorization: Bearer a1b2c3d4e5f6..." \
  -H "X-App-ID: my-app"

Error Handling

All errors return a JSON response with an error field.

Status	Meaning
`400`	Invalid request — check your request body
`401`	Missing or invalid API key / App ID
`402`	Plan limit reached — upgrade required
`404`	Resource not found
`429`	Rate limit exceeded — back off and retry
`500`	Server error

Support

Need help or found a bug? Join our developer community on Discord for quick support, or reach out via the Contact Form.

Authentication​

API Key Types​

Authentication Headers​

Endpoints​

Short Links Management​

GET /api/manage/short-links​

POST /api/manage/short-links​

PATCH /api/manage/short-links​

Link Management​

GET /api/manage/links​

Analytics​

GET /api/analytics/stats​

Error Handling​

Support​

Authentication

API Key Types

Authentication Headers

Endpoints

Short Links Management

GET /api/manage/short-links

POST /api/manage/short-links

PATCH /api/manage/short-links

Link Management

GET /api/manage/links

Analytics

GET /api/analytics/stats

Error Handling

Support