POST /datasets — Create a Dataset

Create a new dataset in a repository to store tabular or time-series data. Requires name and repositoryId. Optionally add source metadata.

Creating a dataset registers a named container within a repository where you can then upload tabular or time-series data. You must have at least Write permission on the target repository. Once created, upload data to the dataset using PUT /datasets/{id}/data.

Authentication

Authenticate using HTTP Basic Auth. Pass your API key as the username and leave the password empty. You must have Write permission on the target repository.

Request

Method: POST
URL: https://api.alphacast.io/datasets

Body parameters

name · string · required

The display name for the new dataset. Must be a non-empty string.

repositoryId · integer · required

The numeric ID of the repository in which to create the dataset. You must have Write permission on this repository.

description · string

A human-readable description of the dataset’s contents, intended audience, or methodology.

sourceUrl · string

The URL of the original data source, for provenance tracking.

sourceName · string

The name of the organization or publication that originally produced this data.

Response

Returns 201 Created with the newly created dataset object.

id · integer

The numeric ID assigned to the new dataset. Use this in all subsequent requests.

name · string

The name you provided.

repositoryId · integer

The repository the dataset was created in.

description · string

The description you provided, or null if omitted.

sourceName · string

The source name you provided, or null if omitted.

sourceUrl · string

The source URL you provided, or null if omitted.

permission · string

Your permission level on the new dataset. Will be Admin for datasets you create.

Example

cURL

curl -u YOUR_API_KEY: \
  -X POST https://api.alphacast.io/datasets \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US GDP Quarterly",
    "repositoryId": 45,
    "description": "Quarterly US GDP figures from BEA",
    "sourceName": "Bureau of Economic Analysis",
    "sourceUrl": "https://www.bea.gov/data/gdp"
  }'

import requests

response = requests.post(
    "https://api.alphacast.io/datasets",
    auth=("YOUR_API_KEY", ""),
    json={
        "name": "US GDP Quarterly",
        "repositoryId": 45,
        "description": "Quarterly US GDP figures from BEA",
        "sourceName": "Bureau of Economic Analysis",
        "sourceUrl": "https://www.bea.gov/data/gdp",
    },
)
dataset = response.json()

const response = await fetch("https://api.alphacast.io/datasets", {
  method: "POST",
  headers: {
    Authorization: "Basic " + btoa("YOUR_API_KEY:"),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "US GDP Quarterly",
    repositoryId: 45,
    description: "Quarterly US GDP figures from BEA",
    sourceName: "Bureau of Economic Analysis",
    sourceUrl: "https://www.bea.gov/data/gdp",
  }),
});
const dataset = await response.json();

201

{
  "id": 123,
  "name": "US GDP Quarterly",
  "repositoryId": 45,
  "description": "Quarterly US GDP figures from BEA",
  "sourceName": "Bureau of Economic Analysis",
  "sourceUrl": "https://www.bea.gov/data/gdp",
  "permission": "Admin",
  "frequency": null,
  "minDate": null,
  "maxDate": null
}

Error responses

Status	Cause
403 Forbidden	The repository does not exist, or you do not have Write permission on it.
409 Conflict	A dataset with a conflicting configuration already exists.

After creating a dataset, use PUT /datasets/{id}/data to upload your first CSV file and populate the dataset with rows.