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

Request sample

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}"

Java

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class WoodpeckerApiClient {
  public static void main(String[] args) {
    String apiKey = "YOUR_API_KEY"; 
    String endpoint = "https://api.woodpecker.co/rest/v2/users?page=0&sort=-id";

    try {
      URL url = new URL(endpoint);
      HttpURLConnection connection = (HttpURLConnection) url.openConnection();
      connection.setRequestMethod("GET");
      connection.setRequestProperty("x-api-key", apiKey);

      int responseCode = connection.getResponseCode();
      if (responseCode == HttpURLConnection.HTTP_OK) {
        BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
        String inputLine;
        StringBuilder response = new StringBuilder();

        while ((inputLine = in.readLine()) != null) {
          response.append(inputLine);
        }
        in.close();

        System.out.println("Response: " + response.toString());
      } else {
        System.out.println("GET request failed with response code: " + responseCode);
      }

      connection.disconnect();
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Node.js

const axios = require("axios");

const apiKey = "YOUR_API_KEY";
const url = "https://api.woodpecker.co/rest/v2/users?page=0&sort=-id";

axios
  .get(url, {
    headers: {
      "x-api-key": apiKey,
    },
  })
  .then((response) => {
    console.log("Response:", response.data);
  })
  .catch((error) => {
    console.error("Error:", error.response ? error.response.data : error.message);
  });

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	List of users in the account
└─content[].id	integer	Unique identifier of the user
└─content[].name	string	Full name of the user
└─content[].email	string	Email address of the user
└─content[].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

Unknown 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