Skip to main content
This guide walks you through the core workflow of the Alphacast API: creating a repository to hold your data, adding a dataset to it, uploading a file, and retrieving that data in the format of your choice. All examples use curl and the base URL https://api.alphacast.io.
All requests require an API key. See the authentication guide for details on how to obtain and use your key.
1

Get your API key

Log in to alphacast.io and navigate to your account settings to generate an API key. You will use this key to authenticate every request.Alphacast uses HTTP Basic Auth, where the API key is passed as the username with an empty password. The -u flag in curl handles this automatically:
curl https://api.alphacast.io/repositories \
  -u YOUR_API_KEY:
The trailing colon after your API key tells curl to send an empty password, which is required by HTTP Basic Auth.
2

Create a repository

Repositories are the top-level containers that organize your datasets. Every dataset must belong to a repository. Create one by sending a POST request to /repositories:
curl -X POST https://api.alphacast.io/repositories \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Repository",
    "description": "A repository for testing the Alphacast API",
    "privacy": "Private"
  }'
The privacy field accepts "Private" or "Public". A successful response returns 201 with the new repository object:
{
  "id": 42,
  "name": "My First Repository",
  "description": "A repository for testing the Alphacast API",
  "privacy": "Private",
  "permission": "Owner"
}
Note the id — you will need it in the next step.
3

Create a dataset

Within your repository, create a dataset by posting to /datasets. The repositoryId field must match the repository you created above:
curl -X POST https://api.alphacast.io/datasets \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Quarterly GDP",
    "repositoryId": 42,
    "description": "GDP data by quarter",
    "sourceName": "National Statistics Office",
    "sourceUrl": "https://example.com/gdp-data"
  }'
A successful response returns 201 with the dataset object:
{
  "id": 101,
  "name": "Quarterly GDP",
  "repositoryId": 42,
  "description": "GDP data by quarter",
  "sourceName": "National Statistics Office",
  "sourceUrl": "https://example.com/gdp-data"
}
Note the dataset id — you will use it to upload and download data.
4

Upload data

Upload a CSV file to your dataset using a multipart form PUT request to /datasets/{id}/data:
curl -X PUT https://api.alphacast.io/datasets/101/data \
  -u YOUR_API_KEY: \
  -F "data=@gdp.csv"
Your CSV should have a header row. For example:
Date,Country,GDP_USD_Billions
2023-01-01,USA,6823.4
2023-04-01,USA,6901.2
2023-07-01,USA,6987.6
A successful upload returns 201 with a process object describing the upload job:
{
  "id": 500,
  "datasetId": 101,
  "status": "pending",
  "createdAt": "2024-01-15T10:30:00"
}
Uploads are processed asynchronously. The dataset will be available for download once the process status reaches "completed". You can check status at GET /datasets/{id}/processes/{process_id}.
5

Download data

Once the upload is processed, download your dataset using GET /datasets/{id}/data. By default the response is a CSV file:
curl https://api.alphacast.io/datasets/101/data \
  -u YOUR_API_KEY:
You can request other formats using the $format query parameter:
curl "https://api.alphacast.io/datasets/101/data" \
  -u YOUR_API_KEY:
You can also filter and paginate results using OData-style query parameters:
ParameterDescription
$filterOData filter expression, e.g. Country eq 'USA'
$selectComma-separated column names to include
$topMaximum number of rows to return
$lastReturn the last N rows by date

​
Next steps