> For the complete documentation index, see [llms.txt](https://pickalloy.gitbook.io/alloy-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pickalloy.gitbook.io/alloy-docs/important-notes.md).

# Important Notes

## Authentication

{% hint style="warning" %}

* API key authentication is the only supported auth method for this endpoint.
* Ensure your API key is kept secure and never exposed in client-side code.
* Rotate your API keys regularly for security.
  {% endhint %}

## File Limits

{% hint style="info" %}

* **Maximum file size**: 10 MB
* Files larger than 10 MB are rejected with an error response
* Supported formats: CSV and JSON
  {% endhint %}

## Processing Modes

### Synchronous Processing

For small files, the dashboard may be generated immediately and returned in the POST response. This is ideal for quick testing and small datasets.

### Asynchronous Processing

For larger files or complex datasets, processing happens in the background:

{% stepper %}
{% step %}
Use the POST response to retrieve the returned `generation_id` and the `status` value, which will be `"processing"`.
{% endstep %}

{% step %}
Poll the status endpoint using the `generation_id` to check progress and final status.
{% endstep %}

{% step %}
Alternatively, set up [webhook](/alloy-docs/webhooks.md) receive notifications when processing completes.
{% endstep %}

{% step %}
You can also subscribe to your existing websocket channel using the returned `generation_id`.
{% endstep %}
{% endstepper %}

## Share Links

Share-link behavior depends on your plan:

* **Free plan**: Public 7-day links
* **Premium plan**: Private controls with email restrictions and custom expiration

### Premium Features

The following features are only available on premium plans:

* `allowed_emails` - Restrict dashboard access to specific email addresses
* `allow_pdf_export` - Enable PDF export functionality
* `allow_scrollable_cards` - Enable scrollable card layouts

## Error Handling

Always implement proper error handling in your integration:

* Check HTTP status codes (`200` for success, `4xx` for client errors, `5xx` for server errors)
* Handle network timeouts and retries appropriately
* Validate file formats before uploading
* Check file size before making the request

## Rate Limits

Be mindful of rate limits when making multiple requests. If you encounter rate limit errors:

* Implement exponential backoff
* Batch requests when possible
* Contact support if you need higher limits

## Best Practices

{% stepper %}
{% step %}
Validate files before upload — check format and size client-side.
{% endstep %}

{% step %}
Use webhooks — prefer webhooks over polling for better efficiency.
{% endstep %}

{% step %}
Handle async responses — always check the `status` field in responses.
{% endstep %}

{% step %}
Store generation IDs — keep track of `generation_id` values for status checking.
{% endstep %}

{% step %}
Monitor processing — set up monitoring for failed generations.
{% endstep %}

{% step %}
Test thoroughly — test with various file sizes and formats before production use.
{% endstep %}
{% endstepper %}