GET - Users

GET/api/public/users

List all users

Retrieves a paginated list of users from the TechWriter Platform. Use query parameters such as top, skip, orderby, select, filter, and count to paginate, sort, filter, and shape the response.

In production integrations, count is frequently combined with top and skip to calculate total pages for dashboard pagination.

Query parameters

ParameterTypeRequiredExampleDescription

filterstringoptionalemail eq 'admin@techwriter.io'Filter expression that narrows the returned users. Format: field op 'value', where op is the operator. Supported operators: eq (equals), ne (not equals), lt (less than), gt (greater than), le (less than or equal), ge (greater than or equal), contains.

selectstringoptionalfirstName,lastName,emailComma-separated list of response properties to include. Omit to receive all fields.

topintegeroptional20Maximum number of users to return.

skipintegeroptional0Number of users to skip before returning results. Use with top for offset pagination.

orderbystringoptionallastName ascSort expression: a field name followed by asc or desc.

countbooleanoptionaltrueWhen true, the response includes data.totalCount — the total matching users before pagination.

Request headers

HeaderValueRequiredDescription

AuthorizationBearer {YOUR_BEARER_TOKEN}requiredAccess token used to authenticate the API request.

Accept*/*optionalIndicates the response formats the client can accept.

Response fields

Returned on a successful 200 OK response.

FieldTypeDescription

data.totalCountintegerTotal number of users that match the query.

data.itemsobject[]List of returned user objects. Optional — may be an empty array (minimum 0 items) when no users match the query.

data.items[].userIdintegerUnique numeric identifier of the user (employee number). Example: 12734.

data.items[].emailstringUser's email address.

data.items[].firstNamestringUser's first name.

data.items[].lastNamestringUser's last name.

data.items[].isActivebooleanIndicates whether the account is active.

data.items[].rolestringSystem role (admin, editor, viewer).

data.items[].createdAtstringUser creation timestamp in ISO 8601 format.

data.items[].lastLoginstring | nullTimestamp of the most recent login in ISO 8601 format, or null if the user has never logged in.

successbooleanIndicates whether the request completed successfully.

Response codes

The API uses conventional HTTP status codes. Codes in the 2xx range indicate success, 4xx indicate client errors, and 5xx indicate server-side issues.

StatusDescription

200 OKUsers retrieved successfully.

400 Bad RequestThe request is malformed or contains an invalid query parameter.

401 UnauthorizedAuthentication failed or the bearer token is missing.

403 ForbiddenThe token is valid but lacks permission to read users.

404 Not FoundThe requested resource or endpoint does not exist.

422 UnprocessableA filter expression could not be parsed.

429 Too ManyYou exceeded the rate limit. Retry after the specified delay.

500 Server ErrorAn unexpected error occurred on the TechWriter side.

503 UnavailableThe service is temporarily down for maintenance or overloaded.

Was this section helpful?

Example request

curl -X GET "{{env_base_uri}}/api/public/users?count=true&top=2" \
  -H "Authorization: Bearer {YOUR_BEARER_TOKEN}" \
  -H "Accept: */*"

Example response

200 OKUsers retrieved successfully.

{
  "data": {
    "totalCount": 150,
    "items": [
      {
        "userId": 12734,
        "email": "john.doe@techwriter.io",
        "firstName": "John",
        "lastName": "Doe",
        "isActive": true,
        "role": "admin",
        "createdAt": "2024-01-15T09:00:00+00:00",
        "lastLogin": "2026-04-08T14:20:11+00:00"
      },
      {
        "userId": 5892,
        "email": "jane.smith@techwriter.io",
        "firstName": "Jane",
        "lastName": "Smith",
        "isActive": true,
        "role": "editor",
        "createdAt": "2024-02-10T11:30:45+00:00",
        "lastLogin": null
      }
    ]
  },
  "success": true
}

Pagination tip

Combine count=true with top and skip to drive paginated tables. Divide data.totalCount by your page size to get the total page count.