atypica.AI

atypica.AI Docs

Developer Documentation

Quick Start

Embed atypica.AI into your application and communicate with it using the postMessage API for bidirectional communication.

1. Embed the iframe

Use the impersonation login URL to automatically authenticate users. You can obtain the login URL from the Impersonation API endpoint.

<iframe
  id="atypica-iframe"
  src="https://atypica.ai/auth/impersonation-login?token=YOUR_TOKEN"
  width="100%"
  height="800px"
  frameborder="0"
></iframe>

2. Listen for messages

window.addEventListener("message", function (event) {
  if (event.data.source !== "atypica") {
    return; // Ignore non-atypica messages
  }

  console.log("Received message:", event.data);
  // Handle message...
});

3. Send messages

const iframe = document.getElementById("atypica-iframe");
iframe.contentWindow.postMessage(
  {
    target: "atypica",
    type: "check_auth",
    timestamp: new Date().toISOString(),
  },
  "*"
);

Message Protocol

All messages use JSON format with the following base fields:

FieldTypeRequiredDescription
sourcestringYes (responses)Fixed value "atypica"
targetstringYes (requests)Fixed value "atypica"
typestringYesMessage type
timestampstringYesISO 8601 timestamp

Authentication

Check Authentication Status

Request authentication status from the embedded iframe:

Request

{
  "target": "atypica",
  "type": "check_auth",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Response

{
  "source": "atypica",
  "type": "auth_status",
  "authenticated": true,
  "user": {
    "email": "user@example.com"
  },
  "timestamp": "2024-01-01T12:00:00.000Z"
}

URL Change Notifications

The iframe automatically sends notifications when the URL changes:

{
  "source": "atypica",
  "type": "href",
  "href": "https://atypica.ai/study/xxx",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Actions

Create Study Chat

Create a new research conversation and navigate to it:

Request

{
  "target": "atypica",
  "type": "action",
  "action": "createStudyUserChat",
  "args": {
    "content": "Analyze Apple's latest financial report"
  },
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Response

{
  "source": "atypica",
  "type": "action_result",
  "action": "createStudyUserChat",
  "result": {
    "token": "study-chat-token-123",
    "id": "chat-id-456"
  },
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Fetch Analyst Reports

Retrieve analyst reports from the current study chat (only works on /study/[token] pages):

Request

{
  "target": "atypica",
  "type": "action",
  "action": "fetchAnalystReportsOfStudyUserChat",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Response

{
  "source": "atypica",
  "type": "action_result",
  "action": "fetchAnalystReportsOfStudyUserChat",
  "result": [
    {
      "token": "report-token-1",
      "onePageHtml": "<html>...</html>"
    }
  ],
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Error Responses

When an action fails, you'll receive an error response:

{
  "source": "atypica",
  "type": "action_error",
  "action": "createStudyUserChat",
  "error": "Content cannot be empty",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Complete Example

A complete workflow example demonstrating auto-login, creating a study, and fetching reports:

<!DOCTYPE html>
<html>
  <head>
    <title>atypica.AI Embed Example</title>
  </head>
  <body>
    <iframe
      id="atypica-iframe"
      src="https://atypica.ai/auth/impersonation-login?token=YOUR_TOKEN"
      width="100%"
      height="800px"
    ></iframe>

    <div id="results"></div>

    <script>
      const iframe = document.getElementById("atypica-iframe");
      let currentUrl = "";

      // Listen for messages
      window.addEventListener("message", function (event) {
        if (event.data.source !== "atypica") return;

        console.log("Received:", event.data);

        // Track URL changes
        if (event.data.type === "href") {
          currentUrl = event.data.href;

          // Auto-create study when on home page
          if (currentUrl.includes("musedam.cc/") &&
              !currentUrl.includes("/study/")) {
            createStudy();
          }

          // Fetch reports when on study page
          if (currentUrl.includes("/study/")) {
            setTimeout(fetchReports, 2000);
          }
        }

        // Handle action results
        if (event.data.type === "action_result") {
          if (event.data.action === "fetchAnalystReportsOfStudyUserChat") {
            displayReports(event.data.result);
          }
        }
      });

      function createStudy() {
        iframe.contentWindow.postMessage({
          target: "atypica",
          type: "action",
          action: "createStudyUserChat",
          args: {
            content: "Analyze Apple's latest earnings"
          },
          timestamp: new Date().toISOString()
        }, "*");
      }

      function fetchReports() {
        iframe.contentWindow.postMessage({
          target: "atypica",
          type: "action",
          action: "fetchAnalystReportsOfStudyUserChat",
          timestamp: new Date().toISOString()
        }, "*");
      }

      function displayReports(reports) {
        const results = document.getElementById("results");
        results.innerHTML = `Found ${reports.length} reports`;
      }
    </script>
  </body>
</html>

Security

Important Security Considerations

  • Always validate the message source domain
  • Filter out non-atypica messages
  • Use HTTPS in production environments
  • Keep impersonation tokens secure

Domain Verification Example

window.addEventListener("message", function (event) {
  // Verify origin domain
  if (event.origin !== "https://your-trusted-domain.com") {
    return;
  }

  // Verify message format
  if (event.data.source !== "atypica") {
    return;
  }

  // Process message...
});

Troubleshooting

iframe fails to load

Verify the URL is correct and that the target page allows iframe embedding (check X-Frame-Options headers).

No response to messages

Ensure the iframe is fully loaded before sending messages. Use a delay or listen for the load event.

iframe.addEventListener("load", function() {
  // iframe is ready, now send messages
  sendMessage();
});

Cross-origin issues

Always use the postMessage API for cross-origin communication. Do not attempt to directly access iframe content.

Action not working on wrong page

Some actions only work on specific routes. For example, fetchAnalystReportsOfStudyUserChat only works on /study/[token] pages. Check the URL using the href message type.

Embed Integration Documentation | atypica.AI