Embeddable Widgets

Create and manage embeddable widgets for your website. Widgets provide ready-to-use UI components for astrology features that can be integrated into any web page with a single script tag.

Required Module

All widget endpoints require the module:embeddable-widgets module to be enabled for your organization.

---

Widget Types

The following widget types are available based on your active modules:

Type	Description	Required Module
natal	Interactive natal chart	natal:calc
synastry	Synastry comparison chart	synastry:calc
transit	Transit chart overlay	transit:calc
composite	Composite relationship chart	composite:calc
moonphase	Moon phase display	moonphase:calc
daily-horoscope	Daily horoscope for all signs	module:daily-report
numerology	Numerology profile form	module:numerology
compatibility	Sun sign compatibility	compatibility:calc
moon-calendar	Monthly moon calendar	moon-calendar:calc

---

Widget Management

List Widgets

curl "https://api.astroapi.cloud/api/widgets" \
  -H "X-Api-Key: your-api-key"

Get Widget

curl "https://api.astroapi.cloud/api/widgets/wgt_abc123" \
  -H "X-Api-Key: your-api-key"

Create Widget

Widgets are created using JSON:API format:

curl -X POST "https://api.astroapi.cloud/api/widgets" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "widgets",
      "attributes": {
        "name": "My Natal Chart Widget",
        "widgetType": "natal",
        "allowedDomains": ["example.com", "www.example.com"],
        "customization": {
          "language": "en",
          "layout": "card",
          "colors": {
            "primary": "#5b2d8e",
            "background": "#ffffff",
            "text": "#1a1a1a"
          },
          "widgetOptions": {
            "showAspects": true,
            "showPoints": true,
            "showHouses": true,
            "chartSize": 500,
            "theme": "light"
          }
        }
      }
    }
  }'

Update Widget

curl -X PATCH "https://api.astroapi.cloud/api/widgets/wgt_abc123" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "widgets",
      "id": "wgt_abc123",
      "attributes": {
        "name": "Updated Widget Name",
        "customization": {
          "language": "nl"
        }
      }
    }
  }'

Delete Widget

curl -X DELETE "https://api.astroapi.cloud/api/widgets/wgt_abc123" \
  -H "X-Api-Key: your-api-key"

---

Widget Response

{
    "data": {
        "type": "widgets",
        "id": "wgt_abc123",
        "attributes": {
            "name": "My Natal Chart Widget",
            "widgetType": "natal",
            "allowedDomains": ["example.com", "www.example.com"],
            "embedCode": "<script src=\"https://cdn.astroapi.cloud/widget.js\" data-widget-id=\"wgt_abc123\"></script>",
            "customization": {
                "language": "en",
                "layout": "card",
                "colors": {
                    "primary": "#5b2d8e",
                    "background": "#ffffff",
                    "text": "#1a1a1a"
                },
                "widgetOptions": {
                    "showAspects": true,
                    "showPoints": true,
                    "showHouses": true,
                    "chartSize": 500,
                    "theme": "light"
                }
            },
            "createdAt": "2024-06-15T12:00:00Z",
            "updatedAt": "2024-06-15T12:00:00Z"
        }
    }
}

---

Regenerate API Key

Regenerate the widget's embedded API key. Use this if the key has been compromised:

curl -X POST "https://api.astroapi.cloud/api/widgets/wgt_abc123/regenerate-key" \
  -H "X-Api-Key: your-api-key"

Key Rotation

After regenerating the key, existing embeds using the old key will stop working immediately. You do not need to update the embed code — the widget ID remains the same.

---

Available Widget Options

Retrieve the widget types available to your organization based on your active modules:

curl "https://api.astroapi.cloud/api/widgets/options" \
  -H "X-Api-Key: your-api-key"

Response

{
    "data": {
        "availableTypes": ["natal", "moonphase", "daily-horoscope"],
        "planFeatures": {
            "canRemoveBranding": false,
            "canUseCustomLogo": false,
            "canUseCustomCss": true,
            "maxDomains": 5
        }
    }
}

Plan Features

Feature	Description
canRemoveBranding	Whether the AstroAPI branding can be hidden
canUseCustomLogo	Whether a custom logo can be shown in place of the default
canUseCustomCss	Whether custom CSS can be injected into the widget
maxDomains	Maximum number of allowed domains per widget

---

Customization Object

The customization object controls the appearance and behavior of the widget:

{
    "colors": {
        "primary": "#5b2d8e",
        "secondary": "#a07cc5",
        "background": "#ffffff",
        "text": "#1a1a1a",
        "border": "#e0e0e0"
    },
    "fonts": {
        "family": "Inter, sans-serif",
        "size": "14px"
    },
    "borders": {
        "radius": "8px",
        "width": "1px"
    },
    "spacing": {
        "padding": "16px",
        "gap": "12px"
    },
    "shadows": {
        "card": "0 2px 8px rgba(0,0,0,0.1)"
    },
    "layout": "card",
    "interaction": {
        "allowUserInput": true,
        "showTooltips": true
    },
    "branding": {
        "showPoweredBy": true,
        "logoUrl": null
    },
    "language": "en",
    "customCss": ".astroapi-widget { font-weight: 500; }",
    "widgetOptions": {
        "showAspects": true,
        "showPoints": true,
        "showHouses": true,
        "chartSize": 500,
        "theme": "light"
    }
}

Customization Fields

Field	Type	Description
colors.primary	string	Primary accent color (hex)
colors.secondary	string	Secondary accent color (hex)
colors.background	string	Widget background color (hex)
colors.text	string	Main text color (hex)
colors.border	string	Border color (hex)
fonts.family	string	CSS font-family value
fonts.size	string	Base font size (CSS value)
borders.radius	string	Border radius for cards and inputs (CSS value)
borders.width	string	Border width (CSS value)
spacing.padding	string	Internal padding (CSS value)
spacing.gap	string	Gap between elements (CSS value)
shadows.card	string	CSS box-shadow for card elements
layout	string	Widget layout style (see below)
interaction.allowUserInput	boolean	Whether users can input their own birth data
interaction.showTooltips	boolean	Show tooltips on hover
branding.showPoweredBy	boolean	Show "Powered by AstroAPI" badge
branding.logoUrl	string | null	Custom logo URL (requires canUseCustomLogo)
language	string	Display language code
customCss	string | null	Custom CSS injection (requires canUseCustomCss)
widgetOptions.showAspects	boolean	Show aspect lines on charts
widgetOptions.showPoints	boolean	Show planet symbols on charts
widgetOptions.showHouses	boolean	Show house divisions on charts
widgetOptions.chartSize	number	Chart size in pixels
widgetOptions.theme	string	Color theme ("light" or "dark")

Layout Options

Value	Description
compact	Minimal space, suitable for sidebars
card	Rounded card with shadow (default)
full	Full-width, no borders
minimal	No background, borderless

---

Embedding a Widget

After creating a widget, copy the embedCode from the response and paste it into your website's HTML:

<!-- Place this where you want the widget to appear -->
<div id="astroapi-widget-container"></div>

<!-- Load the widget script -->
<script
    src="https://cdn.astroapi.cloud/widget.js"
    data-widget-id="wgt_abc123">
</script>

Domain Allowlist

Widgets will only load on domains listed in allowedDomains. Make sure to add all domains (including www variants) where you plan to embed the widget.