cURL Examples

This page provides ready-to-use cURL commands for interacting with the Redirections API. All examples use the production endpoint and realistic fake credentials that you can replace with your own.

Setup

Replace these values in the examples below:

API Key: redir_live_your_key_here (use your actual API key)
Project ID: <project_id> (use your actual project ID)

Production URL: https://api.3xx.app

Lookup a Redirect

Look up a redirect for a specific path. Returns the destination URL, status code, and match type.

curl -X GET \
  "https://api.3xx.app/v1/lookup?project=<project_id>&path=/old-blog" \
  -H "X-API-Key: redir_live_your_key_here"

Expected Response (200 OK):

{
  "destination": "/blog",
  "statusCode": 301,
  "matchType": "exact"
}

No Match (204)

When a path has no matching redirect, the API returns 204 No Content with an empty response body.

curl -X GET \
  "https://api.3xx.app/v1/lookup?project=<project_id>&path=/this-does-not-exist" \
  -H "X-API-Key: redir_live_your_key_here"

Expected Response (204 No Content):

(empty response body)

Note: A 204 response means there is no redirect configured for that path. This is not an error.

Lookup with Specific Version

Look up a redirect using a specific deployment version instead of the latest.

curl -X GET \
  "https://api.3xx.app/v1/lookup?project=<project_id>&path=/old-blog&version=3" \
  -H "X-API-Key: redir_live_your_key_here"

Expected Response (200 OK):

{
  "destination": "/blog",
  "statusCode": 301,
  "matchType": "exact"
}

Export Redirects

Download your redirects in various formats for integration with your infrastructure.

CSV Export

curl -X GET \
  "https://api.3xx.app/v1/export?project=<project_id>&format=csv" \
  -H "X-API-Key: redir_live_your_key_here" \
  -o redirects.csv

HAProxy Configuration

curl -X GET \
  "https://api.3xx.app/v1/export?project=<project_id>&format=haproxy" \
  -H "X-API-Key: redir_live_your_key_here" \
  -o redirects.cfg

Nginx Configuration

curl -X GET \
  "https://api.3xx.app/v1/export?project=<project_id>&format=nginx" \
  -H "X-API-Key: redir_live_your_key_here" \
  -o redirects.conf

Other available formats:

nginx-map-exact - Nginx map file for exact matches
nginx-map-prefix - Nginx map file for prefix matches
haproxy-map-exact - HAProxy map file for exact matches
haproxy-map-prefix - HAProxy map file for prefix matches

Check Rate Limit Headers

Use the -v (verbose) flag to see response headers, including rate limit information.

curl -v -X GET \
  "https://api.3xx.app/v1/lookup?project=<project_id>&path=/old-blog" \
  -H "X-API-Key: redir_live_your_key_here"

Response Headers:

HTTP/2 200
content-type: application/json
x-ratelimit-limit: 100
x-ratelimit-remaining: 95
x-ratelimit-reset: 1705421340
cache-control: public, max-age=300

Rate Limit Headers Explained:

X-RateLimit-Limit: Maximum requests allowed per time window
X-RateLimit-Remaining: Number of requests remaining in current window
X-RateLimit-Reset: Unix timestamp when the rate limit resets

Error Responses

401 Unauthorized (Invalid API Key)

curl -X GET \
  "https://api.3xx.app/v1/lookup?project=<project_id>&path=/old-blog" \
  -H "X-API-Key: invalid_key_here"

Response (401 Unauthorized):

{
  "error": "Unauthorized",
  "code": "INVALID_API_KEY"
}

400 Bad Request (Missing Parameter)

curl -X GET \
  "https://api.3xx.app/v1/lookup?project=<project_id>" \
  -H "X-API-Key: redir_live_your_key_here"

Response (400 Bad Request):

{
  "error": "Missing path parameter",
  "code": "MISSING_PATH"
}

Next Steps

For a complete reference of all error codes and their meanings, see the Error Reference page.

On this page