Generate Dashboard

POST /api/dashboard/generate/

Uploads a CSV or JSON dataset and triggers the standard dashboard-generation pipeline. The API immediately returns a generation_id. For small files the dashboard may finish synchronously and return a dashboard_id plus share link.

Headers

Authorization: Bearer alloy_<your_key>
Content-Type: multipart/form-data

Multipart Payload

Field	Type	Required	Description
file_type	csv | json	✅	Dataset format
file	File	✅	CSV/JSON file (≤10 MB)
title	string	❌	Dashboard title (defaults to dataset name)
instructions	string	❌	Optional AI instructions/prompt
allowed_emails	string	❌	Comma-separated emails (premium only)
allow_pdf_export	bool	❌	Premium-only PDF toggle
allow_scrollable_cards	bool	❌	Premium-only scroll toggle

Example Request

curl

curl -X POST https://api.example.com/api/dashboard/generate/ \
  -H "Authorization: Bearer alloy_yourapikey" \
  -F "file_type=csv" \
  -F "[email protected]" \
  -F "title=Q3 Sales Overview"

Responses

Async Response (large files / background processing)

When the file is large or requires background processing, you'll receive a generation_id to track the status:

response.json

{
  "status": "success",
  "message": "Generation triggered successfully. Dashboard will be created when processing completes.",
  "data": {
    "generation_id": "af52d214-...",
    "dataset_id": "1b0b7d3e-...",
    "status": "processing"
  }
}

Use the generation_id to check the status or set up webhooks for notifications.

Sync Response (small files / completed immediately)

For small files, the dashboard may be generated immediately:

response.json

{
  "status": "success",
  "message": "Dashboard generated successfully",
  "data": {
    "generation_id": "af52d214-...",
    "dashboard_id": "d6ad65c0-...",
    "status": "completed",
    "share_link": {
      "id": "4a5b...",
      "share_url": "https://api.example.com/share/4a5b.../view/",
      "...": "..."
    }
  }
}

---

GET /api/dashboard/generate/{generation_id}/

Fetch the latest state for a generation ID (useful when the POST response returned status: "processing").

Headers

Authorization: Bearer alloy_<your_key>

Path Parameters

Parameter	Type	Description
generation_id	string	The generation ID returned from the POST request

Example Request

curl

curl -X GET https://api.example.com/api/dashboard/generate/af52d214-.../ \
  -H "Authorization: Bearer alloy_yourapikey"

Sample Response

response.json

{
  "status": "success",
  "message": "Generation retrieved successfully",
  "data": {
    "id": "af52d214-...",
    "dataset": "1b0b7d3e-...",
    "instructions": "Focus on Q3 trends",
    "payload": { "...": "..." },
    "created_at": "2025-01-08T10:15:00Z",
    "updated_at": "2025-01-08T10:16:12Z",
    "dashboard": {
      "id": "d6ad65c0-...",
      "title": "Q3 Sales Overview",
      "status": "completed"
    },
    "share_link": {
      "id": "4a5b...",
      "share_url": "https://api.example.com/share/4a5b.../view/",
      "...": "..."
    }
  }
}

Status Values

• processing - Dashboard generation is in progress

• completed - Dashboard has been successfully generated

• failed - Generation encountered an error