ai-actions-api-docs

AI Actions - API Documentation Requirements

Core Rules (credentials)

NEVER hardcode API keys, tokens, credentials, or secrets directly in server.js, actions.json, request templates, README examples, or any other file in the app. ALL credentials must go through installation parameters (iparams) with secure: true where the platform supports it, or through OAuth / platform-supported auth configuration—not through literals in source.

🚨 BLOCKING RULE — 100% STRICT

AI Actions exist. When an action integrates with a third-party API, third-party docs API search is MANDATORY.

Implementation is FORBIDDEN until official documentation is found via web search.

Mandatory Steps (No Exceptions)

1. SEARCH — Use web_search to find official API docs (e.g. "Stripe API create customer", "HubSpot API authentication")
2. FETCH — Use mcp_web_fetch to load the docs URL and extract:
   • Base URL / host
   • Path and HTTP method
   • Authentication (OAuth, Bearer, API key, Basic)
   • Required headers
   • Request body structure
   • Response format
3. CITE — Reference the docs URL in your response
4. IMPLEMENT — Only after steps 1–3. Code must match the fetched docs exactly.

Authentication Best Practices

For Basic Authentication:

• ✅ Use the encode() platform function in request templates for Base64 encoding
• ✅ Example: "Authorization": "Basic <%= encode(iparam.api_key) %>"
• ✅ The encode() function automatically Base64-encodes the value (e.g., APIKEY:X format)
• ❌ Never manually Base64-encode in server.js when request templates support encode()

Example request template with Basic auth:

{
  "getResource": {
    "schema": {
      "method": "GET",
      "host": "<%= iparam.domain %>",
      "path": "/api/v2/resource",
      "headers": {
        "Authorization": "Basic <%= encode(iparam.api_key) %>",
        "Content-Type": "application/json"
      }
    }
  }
}

If Docs Cannot Be Found