API Documentation

Reference for the Mozilla Data Collective REST API. Programmatically access community-driven datasets in any programming language.

Base URL

All API requests should be made to the following base URL:

https://dev.mozilladatacollective.com/api

Authentication

All authenticated endpoints require an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

You can create and manage your API keys in your profile settings.

API Endpoints

Health

Service health check.

Health check
GET/health

Returns 200 while the application is serving. Unauthenticated, and does not touch the database.

Authentication
Not Required
Success Response (200)
{
  "status": "ok"
}

Datasets

Browse, download, and fetch metadata for datasets.

List and search datasets
GET/datasets

The public dataset catalog. List or search through all available datasets. The filter options may be listed by listDatasetFilters.

Authentication
Not Required
Query Parameters
q

string

example: swahili speechOptional

Query string

limit

integer

Optional

Results per page

page

integer

example: 1Optional

1-based page number

task

DatasetTask[]

example: ASROptional

Machine-learning task

locale

string[]

Optional

Language or locale code

license

string[]

Optional

License abbreviation

format

string[]

Optional

File format

sort

"relevance" | "newest" | "size"

Optional

Result ordering

sortDirection

"asc" | "desc"

Optional

Direction for the sort field

uploadDate

"today" | "thisWeek" | "thisMonth" | "thisYear"

Optional

Publishing window for the datasets

sample

string

Optional

Dataset has a sample file

pricing

"compensated" | "free"

Optional

What pricing options to include

Success Response (200)
{
  "items": [
    {
      "id": "cmt95wvb80027qb6e2vezm3d9",
      "slug": "mcv-el-v22.0",
      "name": "CV 22 Greek",
      "shortDescription": "Common Voice Greek dataset version 22.0",
      "longDescription": "Community-generated audio dataset featuring Greek speech recordings for ASR training.",
      "sizeBytes": 15440281600,
      "checksum": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "createdAt": "2026-08-27T12:00:00.000Z",
      "organization": {
        "name": "CV 22 Greek",
        "slug": "mcv-el-v22.0"
      },
      "pricing": {
        "isPaid": true,
        "basePriceCents": 10000,
        "currency": "usd",
        "platformFeeRate": "0.05",
        "platformFeeCents": 500,
        "totalPriceCents": 10500
      },
      "locale": "el",
      "license": "Creative Commons Zero v1.0 Universal (CC0-1.0)",
      "licenseAbbreviation": "CC0-1.0",
      "task": "ASR",
      "format": "MP3",
      "datasetUrl": "https://dev.mozilladatacollective.com/datasets/cmt95wvb80027qb6e2vezm3d9",
      "filename": "mcv-el-v22.0.tar.gz",
      "submissionId": "cmt95wvb80027qb6e2vezm3d9"
    }
  ],
  "total": 128
}
Error Responses
400

A parameter that does not parse

429

Rate limit exceeded

List the available filters
GET/datasets/filters

The values GET /datasets can currently be narrowed by. Every value except a task is drawn from the published catalog, so it appears only while some dataset carries it; the task vocabulary is fixed and always complete. Filtering on a value absent from this response matches nothing rather than failing.

Authentication
Not Required
Success Response (200)
{
  "tasks": [
    "ASR"
  ],
  "locales": [
    "el"
  ],
  "licenses": [
    "CC0-1.0"
  ],
  "formats": [
    "MP3"
  ]
}
Error Responses
429

Rate limit exceeded

Get dataset details
GET/datasets/{datasetId}

Retrieves the public summary of a dataset by its ID or URL slug. Requires no credentials, like the catalog listing.

Authentication
Not Required
Path Parameters
datasetId

string

examples: cmt95wvb80027qb6e2vezm3d9, mcv-el-v22.0

Dataset ID or slug

Success Response (200)
{
  "id": "cmt95wvb80027qb6e2vezm3d9",
  "slug": "mcv-el-v22.0",
  "name": "CV 22 Greek",
  "shortDescription": "Common Voice Greek dataset version 22.0",
  "longDescription": "Community-generated audio dataset featuring Greek speech recordings for ASR training.",
  "sizeBytes": 15440281600,
  "checksum": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "createdAt": "2026-08-27T12:00:00.000Z",
  "organization": {
    "name": "CV 22 Greek",
    "slug": "mcv-el-v22.0"
  },
  "pricing": {
    "isPaid": true,
    "basePriceCents": 10000,
    "currency": "usd",
    "platformFeeRate": "0.05",
    "platformFeeCents": 500,
    "totalPriceCents": 10500
  },
  "locale": "el",
  "license": "Creative Commons Zero v1.0 Universal (CC0-1.0)",
  "licenseAbbreviation": "CC0-1.0",
  "task": "ASR",
  "format": "MP3",
  "datasetUrl": "https://dev.mozilladatacollective.com/datasets/cmt95wvb80027qb6e2vezm3d9",
  "filename": "mcv-el-v22.0.tar.gz",
  "submissionId": "cmt95wvb80027qb6e2vezm3d9"
}
Error Responses
400

Invalid dataset ID or slug

404

Dataset not found

429

Rate limit exceeded

Create dataset download
POST/datasets/{datasetId}/download

Returns a presigned storage URL. The caller must already satisfy the dataset's access requirements — terms agreement, an approved access request, and payment for a paid dataset. Those are completed in the web interface, not through the API.

Authentication
Required
Path Parameters
datasetId

string (cuid)

example: cmt95wvb80027qb6e2vezm3d9

Dataset ID

Success Response (200)
{
  "accessRecordId": "cmt95wvb80027qb6e2vezm3d9",
  "downloadToken": "dlt_6035b24f-d2fe-4afa-9969-c1eb2b7d5d37",
  "downloadUrl": "https://storage.example.com/datasets/cmt95.../dataset.tar.gz?X-Amz-Signature=...",
  "expiresAt": "2026-08-27T12:00:00.000Z",
  "sizeBytes": "15440281600",
  "contentType": "application/gzip",
  "filename": "mcv-el-v22.0.tar.gz",
  "checksum": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}
Error Responses
400

Invalid dataset ID

401

Missing or invalid API key

402

Payment required for this paid dataset

403

Terms of use not agreed, or access request not approved

404

Dataset not found

429

Rate limit exceeded: download quota reached

Create sample download
POST/datasets/{datasetId}/sample-download

Returns a presigned storage URL for the dataset's public sample file, where one is published.

Authentication
Required
Path Parameters
datasetId

string (cuid)

example: cmt95wvb80027qb6e2vezm3d9

Dataset ID

Success Response (200)
{
  "downloadUrl": "https://storage.example.com/datasets/cmt95.../dataset.tar.gz?X-Amz-Signature=...",
  "filename": "mcv-el-v22.0.tar.gz",
  "sizeBytes": "15440281600",
  "contentType": "application/gzip",
  "expiresAt": "2026-08-27T12:00:00.000Z"
}
Error Responses
401

Missing or invalid API key

404

Dataset not found, or it publishes no sample

429

Rate limit exceeded: sample downloads

Get Croissant metadata
GET/datasets/{datasetId}/metadata

Croissant 1.0 JSON-LD describing the dataset. Public and unauthenticated, and served with an hour of cache: it exists to be indexed by dataset search engines.

Authentication
Not Required
Path Parameters
datasetId

string (cuid)

example: cmt95wvb80027qb6e2vezm3d9

Dataset ID

Success Response (200)
{
  "@context": {
    "@vocab": "https://schema.org/",
    "cr": "http://mlcommons.org/croissant/"
  },
  "@type": "sc:Dataset",
  "@id": "https://dev.mozilladatacollective.com/datasets/cmt95wvb80027qb6e2vezm3d9",
  "name": "CV 22 Greek",
  "description": "Community-generated audio dataset featuring Greek speech recordings.",
  "conformsTo": "http://mlcommons.org/croissant/1.0",
  "citeAs": "mcv-el-v22.0",
  "creator": {
    "@type": "sc:Organization",
    "name": "CV 22 Greek",
    "url": "https://dev.mozilladatacollective.com/"
  },
  "publisher": {
    "@type": "sc:Organization",
    "name": "CV 22 Greek",
    "url": "https://dev.mozilladatacollective.com/"
  },
  "dateCreated": "2026-08-27T12:00:00.000Z",
  "datePublished": "2026-08-27T12:00:00.000Z",
  "inLanguage": "el",
  "keywords": [
    "ASR"
  ],
  "license": "https://creativecommons.org/publicdomain/zero/1.0/",
  "url": "https://dev.mozilladatacollective.com/datasets/cmt95wvb80027qb6e2vezm3d9",
  "version": "22.0",
  "contentSize": "15440281600",
  "rai:mlTask": "ASR",
  "encodingFormat": [
    "audio/mpeg"
  ]
}
Error Responses
404

Dataset not found

422

Valid Croissant metadata could not be produced

Submissions

Create, edit, and submit datasets for review.

Create submission
POST/submissions

Creates a draft dataset submission for the caller's organization. The organization must be approved to publish datasets.

Authentication
Required
Request Body

Initial submission fields

{
  "name": "CV 22 Greek",
  "longDescription": "Community-generated audio dataset featuring Greek speech recordings."
}
Success Response (200)
{
  "submission": {
    "id": "cmt95wvb80027qb6e2vezm3d9",
    "organizationId": "cmt95wvb80027qb6e2vezm3d9",
    "createdBy": "cmt95wvb80027qb6e2vezm3d9",
    "fileReferenceId": "18a95abf-5f3a-46e0-88cc-85432a90a9aa",
    "sampleFileReferenceId": "18a95abf-5f3a-46e0-88cc-85432a90a9aa",
    "status": "draft",
    "name": "CV 22 Greek",
    "slug": "mcv-el-v22.0",
    "shortDescription": "Common Voice Greek dataset version 22.0",
    "longDescription": "Community-generated audio dataset featuring Greek speech recordings.",
    "locale": "el",
    "visibility": "private",
    "task": "ASR",
    "format": "MP3",
    "licenseAbbreviation": "CC0-1.0",
    "license": "Creative Commons Zero v1.0 Universal (CC0-1.0)",
    "licenseUrl": "https://creativecommons.org/publicdomain/zero/1.0/",
    "isPaid": true,
    "basePriceCents": 10000,
    "currency": "usd",
    "autoApproveAccessRequests": false,
    "other": "Datasheet markdown for the dataset.",
    "restrictions": "Research use only.",
    "forbiddenUsage": "No re-identification of speakers.",
    "additionalConditions": "Attribution requested in published work.",
    "pointOfContactFullName": "Alex Rivera",
    "pointOfContactEmail": "[email protected]",
    "fundedByFullName": "Mozilla Foundation",
    "fundedByEmail": "[email protected]",
    "legalContactFullName": "Sam Okafor",
    "legalContactEmail": "[email protected]",
    "createdByFullName": "Jordan Blake",
    "createdByEmail": "[email protected]",
    "showContactInfo": false,
    "intendedUsage": "Training and evaluating speech recognition models.",
    "ethicalReviewProcess": "Reviewed by the internal data ethics board.",
    "agreeToSubmit": "2026-08-27T12:00:00.000Z",
    "exclusivityOptOut": "2026-08-27T12:00:00.000Z",
    "submittedAt": "2026-08-27T12:00:00.000Z",
    "approvedDatasetId": "cmt95wvb80027qb6e2vezm3d9",
    "createdAt": "2026-08-27T12:00:00.000Z",
    "updatedAt": "2026-08-27T12:00:00.000Z",
    "expiresAt": "2026-08-27T12:00:00.000Z",
    "fileUploadId": "cmt95wvb80027qb6e2vezm3d9",
    "reviewedBy": "cmt95wvb80027qb6e2vezm3d9",
    "fileUpload": {
      "id": "cmt95wvb80027qb6e2vezm3d9"
    }
  }
}
Error Responses
400

Invalid submission fields

401

Missing or invalid API key

403

Organization is not permitted to create submissions

Get submission
GET/submissions/{submissionId}

The full submission details

Authentication
Required
Path Parameters
submissionId

string (cuid)

example: cmt95wwkv000eqb8y12tzfz41

Submission ID

Success Response (200)
{
  "submission": {
    "id": "cmt95wvb80027qb6e2vezm3d9",
    "organizationId": "cmt95wvb80027qb6e2vezm3d9",
    "createdBy": "cmt95wvb80027qb6e2vezm3d9",
    "fileReferenceId": "18a95abf-5f3a-46e0-88cc-85432a90a9aa",
    "sampleFileReferenceId": "18a95abf-5f3a-46e0-88cc-85432a90a9aa",
    "status": "draft",
    "name": "CV 22 Greek",
    "slug": "mcv-el-v22.0",
    "shortDescription": "Common Voice Greek dataset version 22.0",
    "longDescription": "Community-generated audio dataset featuring Greek speech recordings.",
    "locale": "el",
    "visibility": "private",
    "task": "ASR",
    "format": "MP3",
    "licenseAbbreviation": "CC0-1.0",
    "license": "Creative Commons Zero v1.0 Universal (CC0-1.0)",
    "licenseUrl": "https://creativecommons.org/publicdomain/zero/1.0/",
    "isPaid": true,
    "basePriceCents": 10000,
    "currency": "usd",
    "autoApproveAccessRequests": false,
    "other": "Datasheet markdown for the dataset.",
    "restrictions": "Research use only.",
    "forbiddenUsage": "No re-identification of speakers.",
    "additionalConditions": "Attribution requested in published work.",
    "pointOfContactFullName": "Alex Rivera",
    "pointOfContactEmail": "[email protected]",
    "fundedByFullName": "Mozilla Foundation",
    "fundedByEmail": "[email protected]",
    "legalContactFullName": "Sam Okafor",
    "legalContactEmail": "[email protected]",
    "createdByFullName": "Jordan Blake",
    "createdByEmail": "[email protected]",
    "showContactInfo": false,
    "intendedUsage": "Training and evaluating speech recognition models.",
    "ethicalReviewProcess": "Reviewed by the internal data ethics board.",
    "agreeToSubmit": "2026-08-27T12:00:00.000Z",
    "exclusivityOptOut": "2026-08-27T12:00:00.000Z",
    "submittedAt": "2026-08-27T12:00:00.000Z",
    "approvedDatasetId": "cmt95wvb80027qb6e2vezm3d9",
    "createdAt": "2026-08-27T12:00:00.000Z",
    "updatedAt": "2026-08-27T12:00:00.000Z",
    "expiresAt": "2026-08-27T12:00:00.000Z",
    "fileUploadId": "cmt95wvb80027qb6e2vezm3d9",
    "organization": {
      "platformFeeRate": "0.05"
    },
    "sampleFileReference": {
      "currentVersion": {
        "id": "18a95abf-5f3a-46e0-88cc-85432a90a9aa",
        "fileUpload": {
          "id": "cmt95wvb80027qb6e2vezm3d9",
          "filename": "mcv-el-v22.0.tar.gz",
          "sizeBytes": "15440281600",
          "status": "initiating"
        }
      }
    },
    "dataset": {
      "id": "cmt95wvb80027qb6e2vezm3d9"
    },
    "fileUpload": {
      "id": "cmt95wvb80027qb6e2vezm3d9",
      "filename": "mcv-el-v22.0.tar.gz",
      "sizeBytes": "15440281600",
      "status": "initiating"
    }
  }
}
Error Responses
401

Missing or invalid API key

403

Submission belongs to another organization

404

Submission not found

Update submission
PATCH/submissions/{submissionId}

Updates a submission's fields, some fields cannot be updated after approval

Authentication
Required
Path Parameters
submissionId

string (cuid)

example: cmt95wwkv000eqb8y12tzfz41

Submission ID

Request Body

Fields to change

{
  "name": "CV 22 Greek",
  "shortDescription": "Common Voice Greek dataset version 22.0",
  "longDescription": "Community-generated audio dataset featuring Greek speech recordings.",
  "task": "ASR",
  "locale": "el",
  "format": "MP3",
  "licenseAbbreviation": "CC0-1.0",
  "license": "Creative Commons Zero v1.0 Universal (CC0-1.0)",
  "licenseUrl": "https://creativecommons.org/publicdomain/zero/1.0/",
  "restrictions": "Research use only.",
  "forbiddenUsage": "No re-identification of speakers.",
  "other": "Datasheet markdown for the dataset.",
  "additionalConditions": "Attribution requested in published work.",
  "pointOfContactFullName": "Alex Rivera",
  "pointOfContactEmail": "[email protected]",
  "fundedByFullName": "Mozilla Foundation",
  "fundedByEmail": "[email protected]",
  "legalContactFullName": "Sam Okafor",
  "legalContactEmail": "[email protected]",
  "createdByFullName": "Jordan Blake",
  "createdByEmail": "[email protected]",
  "intendedUsage": "Training and evaluating speech recognition models.",
  "ethicalReviewProcess": "Reviewed by the internal data ethics board.",
  "showContactInfo": false,
  "showComplianceAttributes": false,
  "exclusivityOptOut": false,
  "visibility": "public",
  "isPaid": false,
  "basePriceCents": 10000,
  "currency": "usd",
  "autoApproveAccessRequests": false
}
Success Response (200)
{
  "submission": {
    "id": "cmt95wvb80027qb6e2vezm3d9",
    "organizationId": "cmt95wvb80027qb6e2vezm3d9",
    "createdBy": "cmt95wvb80027qb6e2vezm3d9",
    "fileReferenceId": "18a95abf-5f3a-46e0-88cc-85432a90a9aa",
    "sampleFileReferenceId": "18a95abf-5f3a-46e0-88cc-85432a90a9aa",
    "status": "draft",
    "name": "CV 22 Greek",
    "slug": "mcv-el-v22.0",
    "shortDescription": "Common Voice Greek dataset version 22.0",
    "longDescription": "Community-generated audio dataset featuring Greek speech recordings.",
    "locale": "el",
    "visibility": "private",
    "task": "ASR",
    "format": "MP3",
    "licenseAbbreviation": "CC0-1.0",
    "license": "Creative Commons Zero v1.0 Universal (CC0-1.0)",
    "licenseUrl": "https://creativecommons.org/publicdomain/zero/1.0/",
    "isPaid": true,
    "basePriceCents": 10000,
    "currency": "usd",
    "autoApproveAccessRequests": false,
    "other": "Datasheet markdown for the dataset.",
    "restrictions": "Research use only.",
    "forbiddenUsage": "No re-identification of speakers.",
    "additionalConditions": "Attribution requested in published work.",
    "pointOfContactFullName": "Alex Rivera",
    "pointOfContactEmail": "[email protected]",
    "fundedByFullName": "Mozilla Foundation",
    "fundedByEmail": "[email protected]",
    "legalContactFullName": "Sam Okafor",
    "legalContactEmail": "[email protected]",
    "createdByFullName": "Jordan Blake",
    "createdByEmail": "[email protected]",
    "showContactInfo": false,
    "intendedUsage": "Training and evaluating speech recognition models.",
    "ethicalReviewProcess": "Reviewed by the internal data ethics board.",
    "agreeToSubmit": "2026-08-27T12:00:00.000Z",
    "exclusivityOptOut": "2026-08-27T12:00:00.000Z",
    "submittedAt": "2026-08-27T12:00:00.000Z",
    "approvedDatasetId": "cmt95wvb80027qb6e2vezm3d9",
    "createdAt": "2026-08-27T12:00:00.000Z",
    "updatedAt": "2026-08-27T12:00:00.000Z",
    "expiresAt": "2026-08-27T12:00:00.000Z",
    "fileUploadId": "cmt95wvb80027qb6e2vezm3d9",
    "reviewedBy": "cmt95wvb80027qb6e2vezm3d9",
    "fileUpload": {
      "id": "cmt95wvb80027qb6e2vezm3d9"
    }
  }
}
Error Responses
400

Invalid submission fields

401

Missing or invalid API key

403

Insufficient permissions to edit submission

404

Submission not found

Submit for review
POST/submissions/{submissionId}

Submits a draft dataset for review

Authentication
Required
Path Parameters
submissionId

string (cuid)

example: cmt95wwkv000eqb8y12tzfz41

Submission ID

Request Body

Confirmation that the submitter agrees to submit

{
  "agreeToSubmit": true
}
Success Response (200)
{
  "submission": {
    "id": "cmt95wvb80027qb6e2vezm3d9",
    "organizationId": "cmt95wvb80027qb6e2vezm3d9",
    "createdBy": "cmt95wvb80027qb6e2vezm3d9",
    "fileReferenceId": "18a95abf-5f3a-46e0-88cc-85432a90a9aa",
    "sampleFileReferenceId": "18a95abf-5f3a-46e0-88cc-85432a90a9aa",
    "status": "draft",
    "name": "CV 22 Greek",
    "slug": "mcv-el-v22.0",
    "shortDescription": "Common Voice Greek dataset version 22.0",
    "longDescription": "Community-generated audio dataset featuring Greek speech recordings.",
    "locale": "el",
    "visibility": "private",
    "task": "ASR",
    "format": "MP3",
    "licenseAbbreviation": "CC0-1.0",
    "license": "Creative Commons Zero v1.0 Universal (CC0-1.0)",
    "licenseUrl": "https://creativecommons.org/publicdomain/zero/1.0/",
    "isPaid": true,
    "basePriceCents": 10000,
    "currency": "usd",
    "autoApproveAccessRequests": false,
    "other": "Datasheet markdown for the dataset.",
    "restrictions": "Research use only.",
    "forbiddenUsage": "No re-identification of speakers.",
    "additionalConditions": "Attribution requested in published work.",
    "pointOfContactFullName": "Alex Rivera",
    "pointOfContactEmail": "[email protected]",
    "fundedByFullName": "Mozilla Foundation",
    "fundedByEmail": "[email protected]",
    "legalContactFullName": "Sam Okafor",
    "legalContactEmail": "[email protected]",
    "createdByFullName": "Jordan Blake",
    "createdByEmail": "[email protected]",
    "showContactInfo": false,
    "intendedUsage": "Training and evaluating speech recognition models.",
    "ethicalReviewProcess": "Reviewed by the internal data ethics board.",
    "agreeToSubmit": "2026-08-27T12:00:00.000Z",
    "exclusivityOptOut": "2026-08-27T12:00:00.000Z",
    "submittedAt": "2026-08-27T12:00:00.000Z",
    "approvedDatasetId": "cmt95wvb80027qb6e2vezm3d9",
    "createdAt": "2026-08-27T12:00:00.000Z",
    "updatedAt": "2026-08-27T12:00:00.000Z",
    "expiresAt": "2026-08-27T12:00:00.000Z",
    "fileUploadId": "cmt95wvb80027qb6e2vezm3d9",
    "reviewedBy": "cmt95wvb80027qb6e2vezm3d9",
    "fileUpload": {
      "id": "cmt95wvb80027qb6e2vezm3d9"
    }
  }
}
Error Responses
400

Submission is incomplete, or agreement was not confirmed

401

Missing or invalid API key

403

Insufficient permissions to submit

404

Submission not found

Upload dataset file

Multipart upload of the dataset archive.

Initiate file upload
POST/uploads

Starts a multipart upload for a submission's main dataset file.

Authentication
Required
Request Body

Filename, size and MIME type

{
  "filename": "mcv-el-v22.0.tar.gz",
  "fileSize": 15440281600,
  "mimeType": "application/gzip",
  "submissionId": "cmt95wwkv000eqb8y12tzfz41"
}
Success Response (200)
{
  "fileUploadId": "cmt95wvb80027qb6e2vezm3d9",
  "uploadId": "2~Zm9vYmFyYmF6cXV1eA"
}
Error Responses
400

Invalid filename, size or MIME type

401

Missing or invalid API key

403

Insufficient permissions to edit submission

404

Submission not found

429

Rate limit exceeded: uploads

Get part URL
GET/uploads/{fileUploadId}/parts/{partNumber}

Returns a short-lived URL the client PUTs one part directly up to

Authentication
Required
Path Parameters
fileUploadId

string (cuid)

example: cmt95wvb60025qb6ejzvn3yle

File upload ID

partNumber

integer

example: 1

Part number

Success Response (200)
{
  "url": "https://storage.example.com/datasets/cmt95.../dataset.tar.gz?X-Amz-Signature=...",
  "expiresAt": "2026-08-27T12:00:00.000Z",
  "partNumber": 1
}
Error Responses
400

Invalid part number

401

Missing or invalid API key

403

Upload does not belong to the caller

404

Upload not found

Complete file upload
POST/uploads/{fileUploadId}

Assembles the uploaded parts and attaches the result to the submission's draft file reference.

Authentication
Required
Path Parameters
fileUploadId

string (cuid)

example: cmt95wvb60025qb6ejzvn3yle

File upload ID

Request Body

Upload ID, part ETags and the whole-file checksum

{
  "uploadId": "2~Zm9vYmFyYmF6cXV1eA",
  "parts": [
    {
      "partNumber": 1,
      "etag": "\"c244bd1edcfb6c0c0edb1aabe2f76c93\""
    }
  ],
  "checksum": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}
Success Response (200)
{
  "success": true,
  "fileUploadId": "cmt95wvb80027qb6e2vezm3d9",
  "status": "completed"
}
Error Responses
400

Parts or checksum do not match what storage holds

401

Missing or invalid API key

403

Upload does not belong to the caller

404

Upload not found

409

Upload is not in a completable state

Upload sample file

Multipart upload of the downloadable sample.

Initiate file upload
POST/submissions/{submissionId}/sample

Starts a multipart upload for the submission's sample file

Authentication
Required
Path Parameters
submissionId

string (cuid)

example: cmt95wwkv000eqb8y12tzfz41

Submission ID

Request Body

Filename, size and MIME type

{
  "filename": "mcv-el-v22.0.tar.gz",
  "fileSize": 15440281600,
  "mimeType": "application/gzip",
  "submissionId": "cmt95wwkv000eqb8y12tzfz41"
}
Success Response (200)
{
  "fileUploadId": "cmt95wvb80027qb6e2vezm3d9",
  "uploadId": "2~Zm9vYmFyYmF6cXV1eA"
}
Error Responses
400

Invalid filename, size or MIME type

401

Missing or invalid API key

403

Insufficient permissions to edit submission

404

Submission not found

429

Rate limit exceeded: uploads

Get part URL
GET/submissions/{submissionId}/sample/{fileUploadId}/parts/{partNumber}
Authentication
Required
Path Parameters
submissionId

string (cuid)

example: cmt95wwkv000eqb8y12tzfz41

Submission ID

fileUploadId

string (cuid)

example: cmt95wvb60025qb6ejzvn3yle

File upload ID

partNumber

integer

example: 1

Part number

Success Response (200)
{
  "url": "https://storage.example.com/datasets/cmt95.../dataset.tar.gz?X-Amz-Signature=...",
  "expiresAt": "2026-08-27T12:00:00.000Z",
  "partNumber": 1
}
Error Responses
400

Invalid part number

401

Missing or invalid API key

403

Upload does not belong to the caller

404

Upload not found

Complete file upload
POST/submissions/{submissionId}/sample/{fileUploadId}
Authentication
Required
Path Parameters
submissionId

string (cuid)

example: cmt95wwkv000eqb8y12tzfz41

Submission ID

fileUploadId

string (cuid)

example: cmt95wvb60025qb6ejzvn3yle

File upload ID

Request Body

Upload ID, part ETags and the whole-file checksum

{
  "uploadId": "2~Zm9vYmFyYmF6cXV1eA",
  "parts": [
    {
      "partNumber": 1,
      "etag": "\"c244bd1edcfb6c0c0edb1aabe2f76c93\""
    }
  ],
  "checksum": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}
Success Response (200)
{
  "success": true,
  "fileUploadId": "cmt95wvb80027qb6e2vezm3d9",
  "status": "completed"
}
Error Responses
400

Parts or checksum do not match what storage holds

401

Missing or invalid API key

403

Upload does not belong to the caller

404

Upload not found

409

Upload is not in a completable state

Types

Closed lists a parameter or field can take. A value outside the list is rejected.

DatasetTask

Machine-learning task.

N/ANLPASRLIDTTSMTLMLLMNLUNLGCALLRAGCVMLOTH

MCP Server

The Mozilla Data Collective also speaks the Model Context Protocol, so AI assistants such as Claude, ChatGPT and Cursor can search the catalog directly.

Connecting

Point any MCP client at:

https://dev.mozilladatacollective.com/api/mcp

In Claude, add the URL as a custom connector. For clients configured via JSON, such as Cursor:

{
  "mcpServers": {
    "mozilla-data-collective": {
      "url": "https://dev.mozilladatacollective.com/api/mcp"
    }
  }
}
Tools
searchSearch the public catalog with a natural-language query, optionally narrowed by task, locale, license, format, price, sample availability or publish date. Returns matching datasets as id, title and URL.
fetchFetch the full public details of one dataset by id or slug: description, organization, task, locale, license, format, size and pricing.
list_filtersList the task, locale, license and format values present in the catalog, plus the sort and date-range options and the expansions of the abbreviations. Filter values are matched exactly, so read them from here rather than guessing.

Rate Limiting

The API employs organization-level rate limiting to ensure fair usage and stability. Rate limits apply to both API requests and bandwidth consumption.

Request Rate Limiting

When request limits are exceeded, the API responds with status code 429 and includes these headers:

X-RateLimit-LimitTotal requests allowed in current window
X-RateLimit-RemainingRequests remaining in current window
Retry-AfterSeconds until next request allowed
Download Rate Limiting

Organizations are limited to 30 dataset downloads per day. The limit resets at midnight UTC. When exceeded, the API responds with a 429 error.

Implementation Notes

Resumable Downloads

Storage supports range requests for resumable downloads. If a presigned URL expires during download, request a new URL and resume using Range headers.

Terms Agreement Required

Users must agree to dataset terms through the web interface before downloading. API-only terms agreement is not supported.

Common Error Responses

400
Bad Request

Malformed request or invalid parameters

{
  "error": "Invalid input"
}
401
Unauthorized

Missing or invalid authentication

{
  "error": "Unauthenticated"
}
429
Too Many Requests

Rate limit exceeded. The response carries Retry-After with the seconds to wait.

{
  "error": "Too many requests"
}