Set domain redirect URL

Set the redirect URL for an existing domain where visitors will be redirected when they open your domain. You can set it only after the domain is ready to use, meaning that get domain endpoint returns is_ready as true.

Request

Endpoint

PATCH https://api.woodpecker.co/rest/v2/domains/{domain_name}/set_redirect_url

Headers

x-api-key: {YOUR_API_KEY}
Content-Type: application/json

For details on how to authenticate your requests, please see the authentication guide.

Parameters

Parameter	Required	Type	Description
domain_name	Yes	string	Domain name

Body

{
  "domain_redirect_url": "https://example.com"
}

Body schema

Field	Type	Required	Description
domain_redirect_url	string	Yes	Redirect URL. Use an empty string to remove an existing redirect. A non-empty value must start with http:// or https://

Request samples

Set redirect URL

cURL

curl --request PATCH \
  --url "https://api.woodpecker.co/rest/v2/domains/example.com/set_redirect_url" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "domain_redirect_url": "https://example.com"
  }'

Python

import requests

def set_redirect_url(domain_name):
  url = f"https://api.woodpecker.co/rest/v2/domains/{domain_name}/set_redirect_url"
  headers = {
    "x-api-key": "{YOUR_API_KEY}",
    "Content-Type": "application/json"
  }
  payload = {
    "domain_redirect_url": "https://example.com"
  }

  response = requests.patch(url, headers=headers, json=payload)
  if response.status_code == 202:
    return f"Redirect URL update accepted: {response.status_code}"
  else:
    raise Exception(f"PATCH request failed: {response.status_code}, {response.text}")

if __name__ == "__main__":
  try:
    result = set_redirect_url("example.com")
    print("PATCH response:", result)
  except Exception as e:
    print("Error:", e)

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class WoodpeckerApiClient {
  public static void main(String[] args) {
    try {
      String domainName = "example.com";
      String url = "https://api.woodpecker.co/rest/v2/domains/" + domainName + "/set_redirect_url";
      String jsonData = """
        {
          "domain_redirect_url": "https://example.com"
        }
        """;

      HttpClient client = HttpClient.newHttpClient();
      HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        .header("x-api-key", "{YOUR_API_KEY}")
        .header("Content-Type", "application/json")
        .method("PATCH", HttpRequest.BodyPublishers.ofString(jsonData))
        .build();

      HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
      if (response.statusCode() == 202) {
        System.out.println("PATCH response: Redirect URL update accepted: " + response.statusCode());
      } else {
        throw new Exception("PATCH request failed: " + response.statusCode() + ", " + response.body());
      }
    } catch (Exception e) {
      System.out.println("Error: " + e.getMessage());
    }
  }
}

Node.js

const axios = require('axios');

async function setRedirectUrl(domainName) {
  const url = `https://api.woodpecker.co/rest/v2/domains/${domainName}/set_redirect_url`;
  const headers = {
    'x-api-key': '{YOUR_API_KEY}',
    'Content-Type': 'application/json'
  };
  const data = {
    domain_redirect_url: 'https://example.com'
  };

  try {
    const response = await axios.patch(url, data, { headers });
    console.log('PATCH response:', `Redirect URL update accepted: ${response.status}`);
  } catch (error) {
    console.error('PATCH request failed:', error.response ? error.response.status : error.message);
  }
}

setRedirectUrl('example.com');

PHP

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new Client([
  'base_uri' => 'https://api.woodpecker.co/rest/v2/',
  'headers'  => [
    'x-api-key' => getenv('WOODPECKER_API_KEY'),
    'Content-Type' => 'application/json',
  ],
]);

try {
  $domainName = 'example.com';
  $response = $client->patch("domains/{$domainName}/set_redirect_url", [
    'json' => [
      'domain_redirect_url' => 'https://example.com',
    ],
  ]);
  echo $response->getStatusCode(), "\n";
  echo $response->getBody(), "\n";
} catch (RequestException $e) {
  echo "Error: ", $e->getMessage(), "\n";
  if ($e->hasResponse()) {
    echo $e->getResponse()->getBody(), "\n";
  }
}

Response

Response examples

202

The redirect URL update has been accepted

400

Invalid request or malformed request syntax

{
  "title": "Bad Request",
  "status": 400,
  "details": "error details",
  "timestamp": "2026-05-06T12:00:00Z"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
details	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred

401

Authentication failed. Please review the authentication guide

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "error details",
  "timestamp": "2026-05-06T12:00:00Z"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
detail	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred

422

Returned when the request body is valid JSON but contains invalid or missing fields.

{
  "type": "validation_error",
  "message": "Invalid field(s)",
  "code": "invalid_fields",
  "request_id": "dc4faa0f-78bf-54e9-9d5d-ce9538f2eec5",
  "fields": [
    {
      "field": "domain_name",
      "issue": "not_found",
      "value": "example.com"
    },
    {
      "field": "domain_redirect_url",
      "issue": "Valid format is http://example.com or https://example.com",
      "value": "htt://xxxxx"
    }
  ]
}

Body schema

Field	Type	Description
type	string	Error type
message	string	Error message
code	string	Error code
request_id	string or null	Request identifier when available
fields	array	Fields that failed validation
└─ field	string	Field with a validation issue. Possible fields include domain_name and domain_redirect_url
└─ issue	string	Detailed description of the validation issue
└─ value	string/null	Rejected value, or null for a missing required field

500

Unexpected server error

{
  "title": "Internal Server Error",
  "status": 500,
  "details": "error details",
  "timestamp": "2026-05-06T12:00:00Z"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
details	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred

503

Service unavailable or communication error

{
  "title": "Service Unavailable",
  "status": 503,
  "details": "error details",
  "timestamp": "2026-05-06T12:00:00Z"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
details	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred