OKUrl - Full API Documentation

Authentication

All API requests require a Bearer Token in the header:

Authorization: Bearer okurl_{your_api_key}

Generate a key on the API page. Key format:

okurl_{user_id}_{random_40_chars}

Rate Limiting

Per minute	60 requests
Per day	5,000 requests

Returns HTTP 429 when limit is exceeded.

Response Format

Success:

{"_res": "ok", "id": "123", "slug": "abc", ...}

Error:

{"_res": "err", "code": "error_code", "msg": "Human readable message"}

URL Endpoints

POST /v1/urls/add Create short link

Param	Type	Req	Description
`domain_id`	string	Y	Domain ID
`url`	string	Y	Target URL
`slug`	string	-	Custom slug (5-30 chars), auto-generated if empty
`title`	string	-	Title (auto-fetched if empty)
`pswd`	string	-	Access password
`expiry`	string	-	Expiry (format: 2026-01-01T00:00)
`project_id`	string	-	Project ID

curl -X POST https://okurl.io/v1/urls/add \
  -H "Authorization: Bearer okurl_{key}" \
  -H "Content-Type: application/json" \
  -d '{"domain_id":"1","url":"https://example.com"}'

POST /v1/urls/list List short links

Param	Type	Req	Description
`domain_id`	string	-	Domain ID (filter)
`keyword`	string	-	Search keyword
`tag`	string	-	Filter by tag
`project_id`	string	-	Filter by project
`page`	int	-	Page (default 1)
`limit`	int	-	Per page (default 20, max 100)

POST /v1/urls/detail/:id Get detail

POST /v1/urls/edit/:id Edit short link

Param	Type	Req	Description
`url`	string	Y	Target URL
`slug`	string	Y	Slug
`title`	string	-	Title
`tags`	string	-	Tags (comma-separated)
`notes`	string	-	Notes
`pswd`	string	-	Password
`expiry`	string	-	Expiry
`redirect_type`	string	-	0=default, 1=landing, 2=JS, 3=302, 4=301
`project_id`	string	-	Project ID

POST /v1/urls/delete/:id Delete

Param	Type	Req	Description
`hash`	string	Y	Link hash (from detail/list response)

POST /v1/urls/transfer Transfer guest links

Param	Type	Req	Description
`list`	array	Y	[{"id":"...","hash":"..."}]

GET/v1/urls/analytics/:idLink analytics

GET/v1/urls/exportExport CSV

GET/v1/urls/qr/:idQR Code (PNG)

Domain Endpoints

POST/v1/domains/listList my domains

POST/v1/domains/list_pubList public domains

POST/v1/domains/editEdit domain (multipart/form-data)

Param	Type	Req	Description
`id`	string	Y	Domain ID
`new_domain`	string	-	New domain name
`redirection_method`	string	-	Redirection method
`public_allowed`	string	-	0 or 1
`path_prefix`	string	-	Path prefix (e.g. "s")
`logo`	file	-	Logo image (JPG/PNG)
`delete_logo`	string	-	"true" to delete logo
`collaborators`	JSON string	-	[{"user_id":"...","is_admin":0}]

This endpoint uses multipart/form-data, not JSON.

Team Endpoints

POST/v1/teams/addCreate team

Param	Type	Req	Description
`domain_id`	string	Y	Domain ID
`name`	string	Y	Team name (max 100)

POST/v1/teams/edit/:idEdit team

name (required)

POST/v1/teams/delete/:idDelete team

POST/v1/teams/listList teams

domain_id (required)

POST/v1/teams/member/addAdd member

Param	Type	Req	Description
`team_id`	string	Y	Team ID
`user_id`	string	Y	User ID (SafeID)
`name`	string	-	Display name
`email`	string	-	Email
`position`	string	-	Position/title
`role`	string	-	0=member, 1=manager

POST/v1/teams/member/edit/:idEdit member

name, email, position, role, user_id

POST/v1/teams/member/remove/:idRemove member

POST/v1/teams/member/listList members

team_id (required)

GET/v1/teams/analytics/:idTeam analytics

GET/v1/teams/analytics/compare?domain_id=XCross-team comparison

UTM Template Endpoints

POST/v1/utm-templates/addCreate template

Param	Type	Req	Description
`domain_id`	string	Y	Domain ID
`name`	string	Y	Template name
`utm_source`	string	-	UTM Source
`utm_medium`	string	-	UTM Medium
`utm_campaign`	string	-	UTM Campaign
`utm_term`	string	-	UTM Term
`utm_content`	string	-	UTM Content
`utm_source_platform`	string	-	Source Platform

POST/v1/utm-templates/edit/:idEdit template

Same params as add (all optional except via path :id)

POST/v1/utm-templates/delete/:idDelete template

POST/v1/utm-templates/listList templates

domain_id (required)

Project Endpoints

POST/v1/projects/addCreate project

Param	Type	Req	Description
`domain_id`	string	Y	Domain ID
`name`	string	Y	Project name
`description`	string	-	Description
`utm_tpl_id`	string	-	UTM Template ID
`team_id`	string	-	Team ID

POST/v1/projects/edit/:idEdit project

name, description, status (0=active, 1=archived), utm_tpl_id, team_id

POST/v1/projects/delete/:idDelete project

POST/v1/projects/listList projects

domain_id (required)

Error Codes

Code	Description
`missing_api_key`	Missing Authorization header
`invalid_api_key`	Invalid API key
`rate_limit_exceeded`	Per-minute rate limit exceeded
`daily_limit_exceeded`	Daily rate limit exceeded
`login required`	Login required (token issue)
`domain_404`	Domain not found
`domain_not_allowed`	No permission for this domain
`url_404`	URL not found
`access denied`	Access denied
`team_not_found`	Team not found
`member_not_found`	Team member not found
`template_not_found`	UTM template not found
`project_not_found`	Project not found