Hudu API Patterns

Hudu API Patterns

Overview

The Hudu API is a RESTful JSON API that provides access to companies, assets, asset layouts, articles, asset passwords, websites, folders, procedures, and more. This skill covers authentication, query building, pagination, error handling, and performance optimization patterns.

Anti-triggers

• IT Glue's request model — the other documentation platform here uses a JSON:API envelope with data/attributes wrappers and its own pagination, against Hudu's flat JSON and x-api-key header. Use itglue-api-patterns. Request shapes do not transfer between them.
• A 403 on a password endpoint — that is Hudu's per-API-key password toggle, not a bad key or an expired token, and the same key works everywhere else. Use hudu-passwords.
• Hudu tools missing from the client entirely, or a 401 before any call succeeds — that is a gateway-connection problem; use shared-skills-wyre-gateway-troubleshooting.

Authentication

API Key Authentication

Hudu uses API key authentication via the x-api-key header:

GET /api/v1/companies
x-api-key: YOUR_API_KEY
Content-Type: application/json

Required Headers:

Environment Variables

export HUDU_BASE_URL="https://your-company.huducloud.com"
export HUDU_API_KEY="your-api-key-here"

Base URL Pattern

All API endpoints follow the pattern:

https://[YOUR_DOMAIN]/api/v1/[resource]

For Hudu Cloud instances:

https://your-company.huducloud.com/api/v1/companies

For self-hosted instances:

https://hudu.yourcompany.com/api/v1/companies

API Key Permission Levels

Hudu API keys support granular permission controls:

Administrators configure these in Admin > API Keys when creating or editing a key.

API Naming Differences

Hudu's UI names differ from API endpoint names in several cases. This is critical to get right:

Request and Response Envelope

Hudu uses standard JSON (not JSON:API). Request and single-resource response bodies are wrapped in the singular resource key ({ "company": { ... } }); collections are wrapped in the plural key ({ "companies": [ ... ] }).

See references/examples.md for full CRUD request/response examples.

Filtering

Query Parameter Filtering

Hudu uses simple query parameters for filtering:

GET /api/v1/companies?name=Acme
GET /api/v1/companies?city=Springfield
GET /api/v1/companies?id_in_integration=12345
GET /api/v1/assets?company_id=1
GET /api/v1/asset_passwords?company_id=1&name=Domain
GET /api/v1/articles?company_id=1&name=backup

Common Filter Parameters by Endpoint

Search Parameter

Some endpoints support a search parameter for broader matching:

GET /api/v1/companies?search=Acme

Pagination

Page-Based Pagination

Hudu uses page-based pagination with the page query parameter:

GET /api/v1/companies?page=1
GET /api/v1/companies?page=2
GET /api/v1/companies?page=3

Pagination Details:

Detecting End of Pages

When a page returns fewer than 25 results (or an empty array), you have reached the last page:

async function fetchAllCompanies() {
  const allItems = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `${baseUrl}/api/v1/companies?page=${page}`,
      { headers: { 'x-api-key': apiKey } }
    );

    const data = await response.json();
    const companies = data.companies || [];
    allItems.push(...companies);

    // If fewer than 25 results, we reached the last page
    hasMore = companies.length === 25;
    page++;
  }

  return allItems;
}

Rate Limiting

Rate Limit Details

Hudu enforces rate limits to ensure fair API usage:

Rate Limit Response

When rate limited (HTTP 429):

{
  "error": "Rate limit exceeded. Please wait before making more requests."
}

Retry Strategy

async function requestWithRetry(url, options, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 60;
        const jitter = Math.random() * 5000;
        await sleep(retryAfter * 1000 + jitter);
        continue;
      }

      return response;
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;

      // Exponential backoff with jitter
      const delay = Math.pow(2, attempt) * 1000 + Math.random() * 1000;
      await sleep(delay);
    }
  }
}

CRUD and Company Scoping

Standard REST verbs: POST to the collection, GET on collection or /:id, PUT /:id for updates (send only the fields you're changing), DELETE /:id. DELETE requires explicit API key permission — not all keys can delete records. Several resources also expose /:id/archive and /:id/unarchive as PUT verbs rather than an archived field.

Most child resources are filtered by company rather than nested under it:

GET /api/v1/assets?company_id=123
GET /api/v1/asset_passwords?company_id=123
GET /api/v1/articles?company_id=123
GET /api/v1/websites?company_id=123
GET /api/v1/assets?company_id=123&asset_layout_id=5

See references/examples.md for full request/response bodies per verb.

Error Handling

HTTP Status Codes

Error Response Format

Errors come back as either a single error string or an errors array of strings — handle both. See references/examples.md for the exact shapes and a status-code dispatch helper.

Gotchas

• 403 is about key scope, not key validity. Password access, DELETE, IP whitelist, and company scope are all per-key toggles; a working key can still 403 on one resource.
• 404 often means a wrong HUDU_BASE_URL or a missing /api/v1/ prefix, not a missing record.
• The UI name is not the API name. Passwords are asset_passwords; Processes are procedures.
• Page size is fixed at 25 and there is no total count — you only know you've finished when a page returns fewer than 25 items.

Best Practices

1. Paginate large results - Loop through pages until fewer than 25 results returned
2. Implement retry logic - Handle rate limits (429) and transient errors (500)
3. Cache reference data - Asset layouts rarely change; cache them
4. Use filters - Narrow results server-side rather than client-side filtering
5. Monitor rate limits - Stay under 300 requests per minute
6. Scope by company - Always filter by company_id when possible

Related Skills

• Hudu Companies - Company management
• Hudu Assets - Asset management
• Hudu Articles - Knowledge base articles
• Hudu Passwords - Secure credential storage
• Hudu Websites - Website monitoring