Get a list of users

Retrieve a list of active users in your account. Only confirmed and active accounts will be included.

Request

Endpoint

GET https://api.woodpecker.co/rest/v2/users

Headers

x-api-key: {YOUR_API_KEY}

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

Parameters

By default, the results are sorted by content[].id ascending. You can change the order by using the sort parameter.

Key	Value	Required	Description
sort	+id/-id	No	Sort the results by content[].id. Use - for descending and + for ascending
page	integer	No	Requested results page (0-based)

Request samples

Retrieve newest users

cURL

curl --request GET \
  --url "https://api.woodpecker.co/rest/v2/users?page=0&sort=-id" \
  --header "x-api-key: {YOUR_API_KEY}"

Python

import requests

def getUsers():
  url = "https://api.woodpecker.co/rest/v2/users?page=0&sort=-id"
  headers = {
    "x-api-key": "{YOUR_API_KEY}"
  }

  response = requests.get(url, headers=headers)

  if response.status_code == 200:
    print("GET successful:", response.json())
  else:
    print("GET failed with status:", response.status_code)

if __name__ == "__main__":
  getUsers()

Java

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

public class WoodpeckerApiClient {
  private static final String API_KEY = "{YOUR_API_KEY}";

  public static void main(String[] args) {
    getUsers();
  }

  public static void getUsers() {
    try {
      String url = "https://api.woodpecker.co/rest/v2/users?page=0&sort=-id";

      HttpClient client = HttpClient.newHttpClient();
      HttpRequest request = HttpRequest.newBuilder()
        .uri(new URI(url))
        .header("x-api-key", API_KEY)
        .GET()
        .build();

      HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

      if (response.statusCode() == 200) {
        System.out.println("GET response: " + response.body());
      } else {
        System.err.println("GET request failed: " + response.statusCode());
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Node.js

const axios = require("axios");

async function getUsers() {
  const url = "https://api.woodpecker.co/rest/v2/users?page=0&sort=-id";
  const headers = {
    "x-api-key": "{YOUR_API_KEY}"
  };

  try {
    const response = await axios.get(url, { headers: headers });

    if (response.status === 200) {
      console.log("GET successful:", response.data);
    } else {
      console.error("GET failed with status:", response.status);
    }
  } catch (error) {
    console.error("Request error:", error.response?.status || error.message);
  }
}

getUsers();

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'),
  ],
]);

try {
  $response = $client->get('users', [
    'query' => [
      'page' => 0,
      'sort' => '-id',
    ],
  ]);
  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

200

{
  "content": [
    {
      "id": 1234,
      "name": "Michael Scott",
      "email": "michael@dundermifflin.com",
      "role": "admin"
    },
    {
      "id": 1235,
      "name": "Jim Halpert",
      "email": "jimothy@dundermifflin.com",
      "role": "user"
    }
  ],
  "pagination_data": {
    "total_elements": 2,
    "total_pages": 1,
    "current_page_number": 1,
    "page_size": 50
  }
}

Body schema

Field	Type	Description
content	array[object]	List of users in the account
└─[].id	integer	Unique identifier of the user
└─[].name	string	Full name of the user
└─[].email	string	Email address of the user
└─[].role	string	User's role in the account (admin or user)
pagination_data	object	Pagination information. See the pagination section

400

Invalid request parameters or malformed request syntax.

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Value of page is incorrect." | "Invalid sort parameter. Available values: +id/-id",
  "timestamp": "2025-03-05 17:57:00"
}

401

An issue with authorization. Please review the authorization guide

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid api key",
  "timestamp": "2025-03-05 17:57:00"
}

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, YYYY-MM-DD HH:MM:SS UTC

404

Please review the request URL.

{
  "title": "Not Found",
  "status": 404,
  "detail": "Requested resource does not exist",
  "timestamp": "2025-03-05 17:57:00"
}

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, YYYY-MM-DD HH:MM:SS UTC

500

Unexpected error, please try again later

{
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error has occurred. Please try again later.",
  "timestamp": "2025-03-05 17:57:00"
}

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, YYYY-MM-DD HH:MM:SS UTC

Pagination

The response body contains pagination details. It will support you in navigating through larger datasets.

Each request returns 50 users. Use page parameter to view a specific page.

info

Page parameter is 0-based. Use page=0 to retrieve the first one. pagination_data.current_page_number is 1-based.

"pagination_data": {
  "total_elements": 80,
  "total_pages": 2,
  "current_page_number": 1,
  "page_size": 50
}

Field	Type	Description
pagination_data	object	Pagination information
└─total_elements	integer	Total number of users
└─total_pages	integer	Total number of available pages
└─current_page_number	integer	Current page number (1-based)
└─page_size	integer	Maximum number of items per page