API Reference

Complete API documentation for OpenShortPath endpoints.

Base URL

All API endpoints are prefixed with /api/v1.

Authentication

Include the JWT token in the Authorization header:

Endpoints

Create Short URL

Create a new short URL.

Endpoint: POST /api/v1/shorten

Authentication: Required (JWT)

Request Body:

Note: The slug field is optional. If not provided, a random 5-character slug will be generated.

Response:

Status Codes:

• 201 Created: Short URL created successfully
• 400 Bad Request: Invalid request body or domain not available
• 401 Unauthorized: Authentication required
• 409 Conflict: Short URL with domain and slug already exists
• 500 Internal Server Error: Server error

List Short URLs

Get a paginated list of short URLs for the authenticated user.

Endpoint: GET /api/v1/short-urls

Authentication: Required (JWT)

Query Parameters:

• page (optional): Page number (default: 1)
• limit (optional): Items per page (default: 20, max: 100)

Example Request:

Response:

Status Codes:

• 200 OK: Success
• 401 Unauthorized: Authentication required
• 500 Internal Server Error: Server error

Get Short URL

Get a single short URL by ID.

Endpoint: GET /api/v1/short-urls/:id

Authentication: Required (JWT)

Response:

Status Codes:

• 200 OK: Success
• 401 Unauthorized: Authentication required
• 404 Not Found: Short URL not found
• 500 Internal Server Error: Server error

Update Short URL

Update a short URL by ID.

Endpoint: PUT /api/v1/short-urls/:id

Authentication: Required (JWT)

Request Body:

Note: All fields are optional. Only provided fields will be updated.

Response:

Status Codes:

• 200 OK: Short URL updated successfully
• 400 Bad Request: Invalid request body or domain not available
• 401 Unauthorized: Authentication required
• 404 Not Found: Short URL not found
• 409 Conflict: Short URL with domain and slug already exists
• 500 Internal Server Error: Server error

Delete Short URL

Delete a short URL by ID.

Endpoint: DELETE /api/v1/short-urls/:id

Authentication: Required (JWT)

Response: No content (204)

Status Codes:

• 204 No Content: Short URL deleted successfully
• 401 Unauthorized: Authentication required
• 404 Not Found: Short URL not found
• 500 Internal Server Error: Server error

Error Responses

All error responses follow this format:

Examples

Example: Create Short URL with cURL

Example: Create Short URL with JavaScript