REST API Reference & Integration Guide

v1.0 Production

Learn how to authenticate, dispatch payloads, and trigger your deployed AstroNode pipelines programmatically from backends, Shopify, Zapier, or custom microservices.

Live Telemetry Canvas Studio

Jump to:1. Authentication 2. Request Structure 3. Integration Cookbooks 4. Telemetry & Status Codes

1. Authentication & Security

Bearer Token Authorization

RFC 6750 Standard

Every deployed workflow endpoint is protected by a dedicated, cryptographically generated 24-byte bearer token (`crypto.randomBytes(24)`).

Required HTTP Header:

Authorization: Bearer <your_workflow_bearer_token>

Zero-Trust Security Requirements

Never expose bearer tokens in client-side code: Do not embed tokens in public React, Vue, mobile apps, or frontend bundles. All requests must originate from your secure backend servers or webhook dispatchers.
Environment Variable Storage: Store tokens as server environment variables (e.g. ASTRONODE_BEARER_TOKEN).
Constant-Time Verification: AstroNode validates tokens using crypto.timingSafeEqual() to prevent side-channel timing analysis attacks.

2. Request & Response Specification

Baseline Ingestion Endpoint

POST

application/json

Production Webhook URI:

POSThttps://app.cosmonova.studio/api/webhook/{webhook_id}

Dynamic Ingestion Mapping:

You can pass any arbitrary JSON structure in the POST request body. AstroNode automatically maps top-level and nested fields into the downstream pipeline graph:

AI / LLM Nodes

Payload fields are automatically injected into prompt context and synthesis reasoning.

HTTP / API Nodes

Passed as JSON body or dynamically interpolated into downstream URL query parameters.

App Integrations

Used to format Slack alerts, update HubSpot deals, or upsert PostgreSQL rows.

Standard JSON Response Contract (200 OK):Headers: X-AstroNode-Execution-Id, X-AstroNode-Duration-Ms

{
  "success": true,
  "executionId": "exec_1730623800_4f92bc1e",
  "workflowId": "wf_9f81a7b2-3c4d-4e5f-8a1b-0123456789ab",
  "workflowName": "Stripe Invoice to Slack Dispatcher",
  "timestamp": "2026-11-03T08:30:00.000Z",
  "durationMs": 142,
  "trigger": {
    "type": "webhook.inbound",
    "payload": {
      "event": "invoice.payment_succeeded",
      "amount": 4900.00
    }
  },
  "executedNodes": [
    {
      "nodeId": "http_enrich_1",
      "name": "HubSpot Lead Enrichment",
      "type": "HTTP",
      "status": "SUCCESS",
      "durationMs": 98
    }
  ],
  "output": {
    "status": "dispatched",
    "channel": "#sales-vip-wins",
    "delivered": true
  }
}

3. Integration Cookbooks & Examples

Production TypeScript SDK Pattern

Type-safe, timeout-protected webhook dispatch with error propagation.

// ==============================================================================
// AstroNode REST API Client (Node.js / Next.js / TypeScript)
// ==============================================================================

interface AstroNodeResponse<T = any> {
  success: boolean;
  executionId: string;
  workflowId: string;
  workflowName: string;
  timestamp: string;
  durationMs: number;
  output: T;
  error?: string;
}

export async function triggerWorkflow<T = any>(
  webhookId: string,
  payload: Record<string, any>
): Promise<AstroNodeResponse<T>> {
  const token = process.env.ASTRONODE_BEARER_TOKEN;
  if (!token) {
    throw new Error("Missing ASTRONODE_BEARER_TOKEN environment variable.");
  }

  const endpointUrl = `https://app.cosmonova.studio/api/webhook/${webhookId}`;

  const response = await fetch(endpointUrl, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/json",
      "User-Agent": "AstroNode-SDK/1.0",
    },
    body: JSON.stringify(payload),
    // 15-second edge timeout
    signal: AbortSignal.timeout(15000),
  });

  const data: AstroNodeResponse<T> = await response.json();

  if (!response.ok || !data.success) {
    throw new Error(
      `AstroNode execution failed (${response.status}): ${data.error || response.statusText}`
    );
  }

  return data;
}

// Example Invocation
async function handleCustomerPayment() {
  try {
    const result = await triggerWorkflow("wf_9f81a7b2-3c4d-4e5f-8a1b-0123456789ab", {
      event: "invoice.payment_succeeded",
      customer: {
        id: "cus_9941a",
        email: "alex@enterprise.io",
      },
      amount: 4900.00,
    });

    console.log("Executed successfully in", result.durationMs, "ms");
    console.log("Execution ID for telemetry trace:", result.executionId);
  } catch (err: any) {
    console.error("Pipeline failure:", err.message);
  }
}

4. Status Codes & Telemetry Observability

HTTP Status Codes & Diagnostics

Open Telemetry

Every invocation generates an execution log with latency, token usage, and payloads accessible in the Telemetry Dashboard.

Status Code	Meaning	Root Cause & Recommended Action
200 OK	Execution Succeeded	All nodes in the pipeline completed successfully. The response body contains the final transformed pipeline output.
400 Bad Request	Malformed Payload	The incoming request body is not valid JSON. Ensure your client sets `Content-Type: application/json` and passes a valid JSON object.
401 Unauthorized	Invalid Token	The `Authorization: Bearer <token>` header is missing, malformed, or does not match the active bearer token for this workflow.
404 Not Found	Endpoint Inactive	The specified `webhook_id` does not exist, has been deleted, or is not marked as deployed in the database.
500 Error	Execution Failed	A downstream node failed (e.g. external target API timed out or returned HTTP 5xx). Check the exact error message and payload trace in the Telemetry Dashboard using the `X-AstroNode-Execution-Id` response header.

Ready to test in real-time?

Open the Canvas to design a workflow, deploy it, and trigger it with the cURL or SDK snippet above.

Open Canvas