Getting Started With the Aideworks API

API overview

The Aideworks API is a REST API that accepts and returns JSON. All endpoints are served from https://api.aideworks.com/v1. Authentication uses Bearer tokens — API keys you generate in the dashboard.

The full OpenAPI 3.0 specification with interactive documentation is available at api.aideworks.com/docs. The interactive Swagger interface lets you try every endpoint directly in the browser using your API key.

Step 1 — Generate an API key

API keys are managed in Settings → API Access. ClickGenerate new key and give it a descriptive name that reflects its purpose — for example, CI/CD pipeline or Onboarding automation.

API keys have scopes that control what operations they can perform:

The key is shown only once at creation time — copy it to a secure secrets manager (e.g. an environment variable, GitHub Actions secret, or HashiCorp Vault) immediately.

Step 2 — Make your first request

Test that your key works by listing the domains in your account:

curl https://api.aideworks.com/v1/domains \
  -H "Authorization: Bearer YOUR_API_KEY"

A successful response returns HTTP 200 with a JSON array of your domains:

{
  "data": [
    {
      "id": "dom_01J8X4K...",
      "domain": "example.com",
      "status": "active",
      "created_at": "2025-09-01T10:00:00Z",
      "monitoring": {
        "dns": true,
        "ssl": true,
        "uptime": true,
        "email_security": true
      }
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 50
  }
}

If you receive a 401 Unauthorized response, verify you're passing the key correctly in the Authorization header and that the key hasn't been revoked.

Step 3 — Add a domain via API

Adding a domain programmatically is the key use case for onboarding automation. Use a POST request to /v1/domains:

curl -X POST https://api.aideworks.com/v1/domains \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "newclient.com",
    "monitoring": {
      "dns": true,
      "ssl": true,
      "uptime": true,
      "email_security": true
    },
    "label": "New Client GmbH"
  }'

The response returns the created domain object with its assigned ID. The initial domain intelligence baseline scan begins automatically within 30 seconds across the monitoring pillars you enabled.

Step 4 — Retrieve monitoring results

Fetch the current SSL check results for a specific domain:

curl https://api.aideworks.com/v1/domains/dom_01J8X4K.../ssl \
  -H "Authorization: Bearer YOUR_API_KEY"

The response includes certificate details, expiry date, chain validity, OCSP stapling status, and any active alerts. The same pattern applies for DNS (/v1/domains/:id/dns), uptime (/v1/domains/:id/uptime), and email security (/v1/domains/:id/email-security).

Step 5 — Configure a webhook endpoint

Webhooks let Aideworks push alerts to your own system in real time — useful for triggering workflows in n8n, Zapier, Make, or a custom service.

curl -X POST https://api.aideworks.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/aideworks-webhook",
    "events": ["ssl.expiry.critical", "dns.change.ns", "uptime.down"],
    "secret": "your_signing_secret"
  }'

Aideworks signs webhook payloads with the X-Aideworks-Signature header using HMAC-SHA256 and the secret you provide. Always validate this signature before processing the payload to prevent unauthorized webhook requests.

See the webhook documentation for the full list of event types and payload schemas.

Rate limits and pagination

API requests are rate-limited per API key. Pagination uses?page= and ?per_page= query parameters on all list endpoints. The meta field in list responses includes total counts and current page for implementing pagination in your client.