Alphacast REST API Reference

Explore the Alphacast REST API to manage repositories, datasets, and data providers programmatically from any HTTP client.

The Alphacast API gives you programmatic access to the same data and workflows available in the Alphacast platform. You can list and create repositories, upload and query datasets, and browse data providers — all over standard HTTP. Every response is JSON, and authentication uses your personal API key.

Base URL

All API requests go to the following base URL:

https://api.alphacast.io

Authentication

The API supports two authentication methods. Both accept the same API key, which you can find in your Alphacast account settings.

HTTP Basic Auth (recommended)

Pass your API key as the HTTP Basic Auth username. Leave the password field empty.

curl -u YOUR_API_KEY: https://api.alphacast.io/repositories

Your API key goes in the username field, not the password field. The trailing colon in -u YOUR_API_KEY: tells curl to send an empty password — this is intentional.

Query parameter

You can also pass your API key as a query parameter. This is convenient for quick testing but less secure because the key appears in URLs and server logs.

curl "https://api.alphacast.io/repositories?apiKey=YOUR_API_KEY"

For production integrations, use HTTP Basic Auth or the Alphacast Python SDK which handles authentication for you.

Path conventions

Provider and user-key slugs in path parameters (/providers/{slug}, /user-keys/{slug}) are case-insensitive. FRED, fred, and Fred all resolve to the same provider, so you do not need to normalize casing on the client.

Series IDs in /providers/{slug}/series/{series_id} may contain forward slashes (for example, SDMX-style dataflow paths). See the fetch series reference for examples.

Request format

For POST and PUT requests, send a JSON body with the Content-Type: application/json header:

curl -u YOUR_API_KEY: \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"name": "My Dataset", "repositoryId": 42}' \
  https://api.alphacast.io/datasets

Data export formats

When downloading dataset data from GET /datasets/{id}/data, you can control the output format with the $format query parameter:

Format	Value	Notes
CSV	csv	Default if $format is omitted
JSON	json	—
Excel	xlsx	—
TSV	tsv	Tab-separated values

# Download as Excel
curl -u YOUR_API_KEY: \
  "https://api.alphacast.io/datasets/123/data?\$format=xlsx" \
  --output data.xlsx

Pagination

Most listing endpoints (GET /repositories, GET /datasets, GET /providers) return the full set of results your API key can access, without server-side paging. Filter the response client-side using the fields described on each endpoint page.

Two endpoints expose explicit pagination controls:

Endpoint	Parameters	Notes
GET /datasets/{id}/data	$top, $last, $filter	When $top or $last is set, the response includes a Row-Count header with the total row count before truncation. Use it to drive pagination UI.
GET /providers/{slug}/browse?series=true	limit (max 1000, default 200), offset	Standard limit/offset paging when listing series under a provider category.

Idempotency

Idempotency follows standard HTTP semantics:

• GET, PUT, and DELETE are idempotent. Repeating the same request produces the same final state.
• POST is not idempotent. Retrying a POST /repositories or POST /datasets creates a new resource each time. Treat client-side retries with care; on network errors, prefer GET to verify whether the previous request succeeded before retrying.

The API does not currently honor an Idempotency-Key header. If you need at-most-once semantics for a POST, deduplicate at the client by checking for an existing resource with the same name before retrying.

Rate limits

Alphacast does not enforce a global rate limit on the API. However, some third-party data providers impose their own restrictions, which Alphacast respects on your behalf. When an upstream limit is hit, the API returns 429 Too Many Requests with an error message naming the provider. For example, FRED inherits its public rate limit; BLS allows up to 25 requests per day without a registered BLS API key.

If you exceed an upstream limit, requests to that provider’s data will fail with 429 until the limit resets. Other providers are not affected.

Raise an upstream limit by saving your own API key for that provider with PUT /user-keys/{slug}. For BLS, register for a free key at bls.gov; for FRED, at fred.stlouisfed.org.

API resources

The Alphacast API is organized into the resource groups below. Each group has its own reference page with full endpoint listings, parameters, and example responses.

Repositories

Create and manage repositories, which are the top-level containers for organizing your datasets.

Datasets

Upload, query, and manage datasets — including column configuration, data versioning, and export formats.

Data providers

Browse and query external financial data providers such as FRED, BLS, and market data sources.