# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://pickalloy.gitbook.io/alloy-docs/important-notes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.