Redirections Docs
Sign In
Redirections
API Reference

Lookup Endpoint

Query for a redirect rule by project and path.

Lookup Endpoint

Query for a redirect rule by project ID and URL path.

Endpoint

GET /v1/lookup

Description

The lookup endpoint searches for a redirect rule matching the specified path within a project. It first checks for exact matches (O(1) lookup), then checks prefix matches in priority order.

Returns redirect information if a match is found, or 204 No Content if no redirect is configured for the path.

Parameters

Query Parameters

NameTypeRequiredDescription
projectstringYesProject ID from your dashboard
pathstringYesURL path to lookup (e.g., /blog/old-post)
versionnumberNoSpecific deployment version number to query

Headers

NameTypeRequiredDescription
X-API-KeystringYesAPI key for authentication (format: redir_live_...)

Request Example

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

Query Specific Version

To query a specific deployment version instead of the latest:

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

Response Codes

200 OK - Redirect Found

A redirect rule was found for the specified path.

Response Body:

{
  "destination": "/articles/new-post",
  "statusCode": 301,
  "matchType": "exact"
}

Response Fields:

FieldTypeDescription
destinationstringDestination URL path to redirect to
statusCodenumberHTTP status code (301 permanent or 302 temporary)
matchTypestringMatch type used: exact or starts_with

204 No Content - No Redirect Found

No redirect is configured for the requested path.

Response Body: Empty (no content)

A 204 response indicates the path is not configured for redirection. This is not an error - the path simply has no redirect rule.

400 Bad Request - Missing Required Parameters

One or more required parameters are missing.

Missing project parameter:

{
  "error": "Missing project parameter",
  "code": "MISSING_PROJECT"
}

Missing path parameter:

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

401 Unauthorized - Authentication Error

API key is missing, invalid, or revoked.

Missing API key:

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

Invalid or revoked API key:

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

429 Too Many Requests - Rate Limit or Quota Exceeded

You have exceeded your per-minute rate limit or monthly quota.

Rate limit exceeded:

{
  "error": "Too Many Requests",
  "code": "RATE_LIMIT_EXCEEDED"
}

Monthly quota exceeded:

{
  "error": "Monthly API Quota Exceeded",
  "code": "QUOTA_EXCEEDED"
}

The response includes a Retry-After header indicating when you can retry.

Response Headers

All responses include these headers:

HeaderDescription
Content-Typeapplication/json (for 200) or empty (for 204)
Cache-Controlpublic, max-age=300 (5 minute cache)
X-RateLimit-LimitMaximum requests per minute for your tier
X-RateLimit-RemainingRequests remaining in current minute
X-RateLimit-ResetUnix timestamp when rate limit resets
X-Quota-LimitMonthly quota limit
X-Quota-RemainingRequests remaining this billing period
X-Quota-ResetUnix timestamp when quota resets

For 429 responses, an additional header is included:

HeaderDescription
Retry-AfterSeconds to wait before retrying

Match Precedence

The lookup algorithm checks matches in this order:

  1. Exact matches - Checked first with O(1) hash lookup
  2. Prefix matches - Checked in priority order (lower priority number = higher precedence)

Exact Match Example

Request for /blog/old-post with exact match rule configured:

{
  "destination": "/articles/new-post",
  "statusCode": 301,
  "matchType": "exact"
}

Prefix Match Example

Request for /blog/old-post/comments with prefix match rule for /blog:

{
  "destination": "/articles",
  "statusCode": 302,
  "matchType": "starts_with"
}

Exact matches always take precedence over prefix matches. This allows you to create broad prefix rules with specific exceptions.

Full Examples

Success Response (200 OK)

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

HTTP/2 200 OK
content-type: application/json
cache-control: public, max-age=300
x-ratelimit-limit: 100
x-ratelimit-remaining: 95
x-ratelimit-reset: 1706745600
x-quota-limit: 10000
x-quota-remaining: 9500
x-quota-reset: 1709251200

{
  "destination": "/articles/new-post",
  "statusCode": 301,
  "matchType": "exact"
}

No Content Response (204 No Content)

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

HTTP/2 204 No Content
cache-control: public, max-age=300
x-ratelimit-limit: 100
x-ratelimit-remaining: 94
x-ratelimit-reset: 1706745600
x-quota-limit: 10000
x-quota-remaining: 9499
x-quota-reset: 1709251200

Error Response (401 Unauthorized)

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

HTTP/2 401 Unauthorized
content-type: application/json

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

Error Handling

For complete error documentation, see the Error Reference.

See Also

API Reference

Complete reference for the Redirections Edge Query API.

Export Endpoint

Download redirect configuration in various server formats.

On this page

Lookup EndpointEndpointDescriptionParametersQuery ParametersHeadersRequest ExampleQuery Specific VersionResponse Codes200 OK - Redirect Found204 No Content - No Redirect Found400 Bad Request - Missing Required Parameters401 Unauthorized - Authentication Error429 Too Many Requests - Rate Limit or Quota ExceededResponse HeadersMatch PrecedenceExact Match ExamplePrefix Match ExampleFull ExamplesSuccess Response (200 OK)No Content Response (204 No Content)Error Response (401 Unauthorized)Error HandlingSee Also