Skip to main content

Documentation Index

Fetch the complete documentation index at: https://watermelon.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

When you connect an API to your AI Agent through Actions, you handle sensitive customer data and authentication keys.

​
Scopes & Least-Privilege Keys

Always apply the principle of least privilege — give your API keys access only to what your Action needs.

​
Developer guidelines

  • Create dedicated API credentials for the AI Agent. Don’t reuse admin or personal tokens.
  • Limit scopes to the minimal endpoints required. Example: read-only access for “order lookup” Actions.
  • Avoid wildcard or full-access scopes (*).
  • Rotate API keys periodically (e.g., every 90 days) and revoke unused ones.
Store keys only inside Watermelon’s authentication fields — never hard-code them in schemas or Domain Knowledge.

​
Handling Personal Data (PII)

Actions often exchange personal data such as names, emails, or postal codes. Handle all PII as confidential.
GuidelineImplementation Tip
MinimizeOnly request attributes required by the API (e.g. email, not full address).
Mask where possibleAvoid returning full PII in responses; display partial data like j***@example.com.
Don’t log secretsThe Playground hides tokens, but avoid echoing them in Domain Knowledge or responses.
Use test dataWhen validating or demonstrating Actions, use anonymized examples.
Sensitive info (passwords, credit-card numbers, tokens) should never pass through chat inputs.

​
HTTPS Only & Allow-Listing Base URLs

Watermelon requires HTTPS for all external API calls to ensure encrypted traffic. Checklist
  • Confirm every server in your schema uses https://, not http://.
  • Allow-list known, trusted base URLs in your backend or firewall. This prevents the AI Agent from sending data to unverified hosts.
  • Avoid temporary or test URLs unless absolutely required.
Example: 
servers:
  - url: "https://api.example.com/v1"
    description: "Production"

​
Avoid Dangerous Endpoints (Write/Delete Operations)

Limit Actions to read or safe write endpoints.
Risky EndpointSafer Alternative
DELETE /users/idSkip or protect with manual approval
PATCH /orders/id/statusRestrict to specific statuses
POST /admin/configDon’t expose admin controls to AI Agent
If a write Action is necessary:
  • Require clear user confirmation in Domain Knowledge.
  • Protect it with authentication and idempotency keys.
  • Log requests securely (see below).

​
Data Storage & Retention in Watermelon

Watermelon temporarily processes Action data to complete a conversation. To stay GDPR-compliant:
  • Conversation data is stored in Watermelon’s secure EU infrastructure.
  • API responses are not permanently stored; they are cached only for the session.
  • Logs of failed calls and schema metadata are kept for debugging but contain no customer PII.
  • To remove historical logs or messages, use the account-level data-deletion request feature.
If your organization has its own retention policy, align your Action setup accordingly — e.g., mask data earlier or shorten retention.