{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "Data Studio Datasource Ingestion",
    "description" : "Basepom for all HubSpot Projects",
    "version" : "2026-09-beta",
    "x-hubspot-product-tier-requirements" : {
      "marketing" : "FREE",
      "sales" : "FREE",
      "service" : "FREE",
      "cms" : "FREE",
      "commerce" : "FREE",
      "crmHub" : "FREE",
      "dataHub" : "FREE"
    }
  },
  "servers" : [ {
    "url" : "https://api.hubapi.com"
  } ],
  "tags" : [ {
    "name" : "Advanced"
  }, {
    "name" : "Basic"
  } ],
  "paths" : {
    "/data-studio/data-source/2026-09-beta" : {
      "post" : {
        "tags" : [ "Basic" ],
        "summary" : "Creates a FILE datasource",
        "description" : "Uploads a file (csv, tsv, json, or xlsx) along with a column schema to create a new datasource. Uses multipart/form-data with a request JSON part (containing datasourceName, datasourceType: FILE, and config.file with column definitions) and a file binary part. ",
        "operationId" : "post-/data-studio/data-source/2026-09-beta",
        "parameters" : [ ],
        "requestBody" : {
          "content" : {
            "multipart/form-data" : {
              "schema" : {
                "type" : "object",
                "properties" : {
                  "file" : {
                    "type" : "string",
                    "format" : "binary",
                    "example" : null
                  },
                  "request" : {
                    "type" : "string",
                    "example" : null
                  }
                },
                "example" : null
              },
              "example" : null
            }
          }
        },
        "responses" : {
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "security" : [ {
          "oauth2" : [ "data_integration.data_source.file.write" ]
        } ]
      }
    },
    "/data-studio/data-source/2026-09-beta/json" : {
      "post" : {
        "tags" : [ "Advanced" ],
        "summary" : "Creates a JSON datasource",
        "description" : "Creates a new JSON datasource with a defined column schema and optional inline data.",
        "operationId" : "post-/data-studio/data-source/2026-09-beta/json_/data-studio/data-source/2026-09-beta/json",
        "parameters" : [ ],
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/DataSourceCreateRequest"
              },
              "example" : null
            }
          },
          "required" : true
        },
        "responses" : {
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "security" : [ {
          "oauth2" : [ "data-integration-json-datasource-write" ]
        } ]
      }
    },
    "/data-studio/data-source/2026-09-beta/{datasourceId}" : {
      "get" : {
        "tags" : [ "Basic" ],
        "summary" : "Retrieve data source",
        "description" : "Retrieve detailed information about a specific data source in HubSpot Data Studio. This endpoint provides details such as the data source's name, type, creation date, and the status of the last data ingestion. It is useful for developers who need to access and manage data sources programmatically.",
        "operationId" : "get-/data-studio/data-source/2026-09-beta/{datasourceId}",
        "parameters" : [ {
          "name" : "datasourceId",
          "in" : "path",
          "description" : "The ID of the datasource.",
          "required" : true,
          "style" : "simple",
          "explode" : false,
          "schema" : {
            "type" : "integer",
            "format" : "int64",
            "example" : null
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/DataSourceGetResponse"
                },
                "example" : null
              }
            }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "security" : [ {
          "oauth2" : [ "data_integration.data_source.file.read" ]
        }, {
          "oauth2" : [ "data-integration-json-datasource-read" ]
        } ]
      },
      "put" : {
        "tags" : [ "Basic" ],
        "summary" : "Update data source",
        "description" : "Update an existing data source in HubSpot Data Studio. This endpoint allows you to modify the details of a specific data source identified by its datasourceId. The request must include a multipart form-data body with the necessary fields to update the data source",
        "operationId" : "put-/data-studio/data-source/2026-09-beta/{datasourceId}",
        "parameters" : [ {
          "name" : "datasourceId",
          "in" : "path",
          "description" : "The ID of the datasource.",
          "required" : true,
          "style" : "simple",
          "explode" : false,
          "schema" : {
            "type" : "integer",
            "format" : "int64",
            "example" : null
          }
        } ],
        "requestBody" : {
          "content" : {
            "multipart/form-data" : {
              "schema" : {
                "type" : "object",
                "properties" : {
                  "file" : {
                    "type" : "string",
                    "format" : "binary",
                    "example" : null
                  },
                  "request" : {
                    "type" : "string",
                    "example" : null
                  }
                },
                "example" : null
              },
              "example" : null
            }
          }
        },
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/DataSourceUpdateResponse"
                },
                "example" : null
              }
            }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "security" : [ {
          "oauth2" : [ "data_integration.data_source.file.write" ]
        } ]
      },
      "delete" : {
        "tags" : [ "Basic" ],
        "summary" : "Delete data source",
        "description" : "Delete a data source in HubSpot Data Studio. This operation is used to remove a specific data source identified by its ID. Ensure that the data source is no longer needed before deletion, as this action cannot be undone.",
        "operationId" : "delete-/data-studio/data-source/2026-09-beta/{datasourceId}",
        "parameters" : [ {
          "name" : "datasourceId",
          "in" : "path",
          "description" : "The ID of the datasource.",
          "required" : true,
          "style" : "simple",
          "explode" : false,
          "schema" : {
            "type" : "integer",
            "format" : "int64",
            "example" : null
          }
        } ],
        "responses" : {
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "security" : [ {
          "oauth2" : [ "data_integration.data_source.file.write" ]
        }, {
          "oauth2" : [ "data-integration-json-datasource-write" ]
        } ]
      },
      "patch" : {
        "tags" : [ "Basic" ],
        "summary" : "Changes display-name of a datasource",
        "description" : "Updates the display-name of a datasource.",
        "operationId" : "patch-/data-studio/data-source/2026-09-beta/{datasourceId}_/data-studio/data-source/2026-09-beta/{datasourceId}",
        "parameters" : [ {
          "name" : "datasourceId",
          "in" : "path",
          "description" : "Identifier of the datasource.",
          "required" : true,
          "style" : "simple",
          "explode" : false,
          "schema" : {
            "type" : "integer",
            "format" : "int64",
            "example" : null
          }
        } ],
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/DataSourceRenameRequest"
              },
              "example" : null
            }
          },
          "required" : true
        },
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/DataSourceUpdateResponse"
                },
                "example" : null
              }
            }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "security" : [ {
          "oauth2" : [ "data_integration.data_source.file.write" ]
        }, {
          "oauth2" : [ "data-integration-json-datasource-write" ]
        } ]
      }
    },
    "/data-studio/data-source/2026-09-beta/{datasourceId}/data-push" : {
      "post" : {
        "tags" : [ "Advanced" ],
        "summary" : "Adds additional records to an existing datasource.",
        "description" : "Push additional data rows to an existing JSON datasource. This enables incremental data ingestion without replacing the entire dataset.",
        "operationId" : "post-/data-studio/data-source/2026-09-beta/{datasourceId}/data-push_/data-studio/data-source/2026-09-beta/{datasourceId}/data-push",
        "parameters" : [ {
          "name" : "datasourceId",
          "in" : "path",
          "description" : "Identifier of datasource",
          "required" : true,
          "style" : "simple",
          "explode" : false,
          "schema" : {
            "type" : "integer",
            "format" : "int64",
            "example" : null
          }
        } ],
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/DataPushRequest"
              },
              "example" : null
            }
          },
          "required" : true
        },
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/DataPushResponse"
                },
                "example" : null
              }
            }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "security" : [ {
          "oauth2" : [ "data-integration-json-datasource-write" ]
        } ]
      }
    },
    "/data-studio/data-source/2026-09-beta/{datasourceId}/json" : {
      "put" : {
        "tags" : [ "Basic" ],
        "summary" : "Updates a JSON datasource",
        "description" : "Update an existing data source in HubSpot Data Studio. This endpoint allows you to fully replace an existing datasource. The schema and the data can be provided in the request.",
        "operationId" : "put-/data-studio/data-source/2026-09-beta/{datasourceId}/json_/data-studio/data-source/2026-09-beta/{datasourceId}/json",
        "parameters" : [ {
          "name" : "datasourceId",
          "in" : "path",
          "description" : "Identifier of the datasource",
          "required" : true,
          "style" : "simple",
          "explode" : false,
          "schema" : {
            "type" : "integer",
            "format" : "int64",
            "example" : null
          }
        } ],
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/DataSourceUpdateRequest"
              },
              "example" : null
            }
          },
          "required" : true
        },
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/DataSourceUpdateResponse"
                },
                "example" : null
              }
            }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "security" : [ {
          "oauth2" : [ "data-integration-json-datasource-write" ]
        } ]
      }
    }
  },
  "components" : {
    "schemas" : {
      "DataPushRequest" : {
        "required" : [ "data" ],
        "type" : "object",
        "properties" : {
          "data" : {
            "type" : "array",
            "description" : "Data ",
            "example" : null,
            "items" : {
              "type" : "object",
              "additionalProperties" : {
                "type" : "object",
                "properties" : { },
                "example" : null
              },
              "example" : null
            }
          }
        },
        "example" : null
      },
      "DataPushResponse" : {
        "required" : [ "datasourceId", "datasourceName", "previewLink" ],
        "type" : "object",
        "properties" : {
          "datasourceId" : {
            "type" : "string",
            "description" : "Identifier of the datasource",
            "example" : null
          },
          "datasourceName" : {
            "type" : "string",
            "description" : "Name of the datasource",
            "example" : null
          },
          "previewLink" : {
            "type" : "string",
            "description" : "Link to preview the datasource",
            "example" : null
          }
        },
        "example" : null
      },
      "DataSourceConfig" : {
        "type" : "object",
        "properties" : {
          "file" : {
            "$ref" : "#/components/schemas/FileStructureRequest"
          },
          "json" : {
            "$ref" : "#/components/schemas/JsonDataRequest"
          }
        },
        "example" : null
      },
      "DataSourceCreateRequest" : {
        "required" : [ "config" ],
        "type" : "object",
        "properties" : {
          "config" : {
            "$ref" : "#/components/schemas/DataSourceConfig"
          },
          "datasourceName" : {
            "type" : "string",
            "description" : "Name of datasource",
            "example" : null
          }
        },
        "example" : null
      },
      "DataSourceGetResponse" : {
        "required" : [ "columns", "createdAt", "datasourceId", "datasourceName", "datasourceType", "lastIngestionStatus" ],
        "type" : "object",
        "properties" : {
          "columns" : {
            "type" : "array",
            "description" : "An array of FileColumn objects representing the columns in the data source.",
            "example" : null,
            "items" : {
              "$ref" : "#/components/schemas/FileColumn"
            }
          },
          "createdAt" : {
            "type" : "string",
            "description" : "The creation date and time of the data source, represented as a string.",
            "example" : null
          },
          "datasourceId" : {
            "type" : "string",
            "description" : "The unique identifier for the data source, represented as a 64-bit integer.",
            "example" : null
          },
          "datasourceName" : {
            "type" : "string",
            "description" : "The name of the data source, represented as a string.",
            "example" : null
          },
          "datasourceType" : {
            "type" : "string",
            "description" : "The type of the data source, which is a string with a valid value of 'FILE'.",
            "example" : null,
            "enum" : [ "FILE", "JSON" ]
          },
          "lastIngestionStatus" : {
            "type" : "string",
            "description" : "The status of the last data ingestion process, represented as a string. Valid values include 'SUCCESSFUL', 'IN_PROGRESS', and 'FAILED'.",
            "example" : null,
            "enum" : [ "FAILED", "IN_PROGRESS", "SUCCESSFUL" ]
          }
        },
        "example" : null
      },
      "DataSourceRenameRequest" : {
        "required" : [ "datasourceName" ],
        "type" : "object",
        "properties" : {
          "datasourceName" : {
            "type" : "string",
            "description" : "New name of datasource. Name cannot be used by another datasource.",
            "example" : null
          }
        },
        "example" : null
      },
      "DataSourceUpdateRequest" : {
        "type" : "object",
        "properties" : {
          "config" : {
            "$ref" : "#/components/schemas/DataSourceConfig"
          },
          "datasourceName" : {
            "type" : "string",
            "description" : "New name of the datasource",
            "example" : null
          }
        },
        "example" : null
      },
      "DataSourceUpdateResponse" : {
        "required" : [ "datasourceId", "datasourceName", "previewLink" ],
        "type" : "object",
        "properties" : {
          "createdAt" : {
            "type" : "string",
            "description" : "Timestamp when the datasource was created.",
            "example" : null
          },
          "datasourceId" : {
            "type" : "string",
            "description" : "The unique identifier for the data source. It is an integer formatted as int64.",
            "example" : null
          },
          "datasourceName" : {
            "type" : "string",
            "description" : "The name of the data source. It is a string.",
            "example" : null
          },
          "previewLink" : {
            "type" : "string",
            "description" : "A URL string that provides a preview link for the data source.",
            "example" : null
          },
          "updatedAt" : {
            "type" : "string",
            "description" : "Timestamp when the datasource was updated.",
            "example" : null
          }
        },
        "example" : null
      },
      "Error" : {
        "required" : [ "category", "correlationId", "message" ],
        "type" : "object",
        "properties" : {
          "category" : {
            "type" : "string",
            "description" : "The error category",
            "example" : null
          },
          "context" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "array",
              "example" : null,
              "items" : {
                "type" : "string",
                "example" : null
              }
            },
            "description" : "Context about the error condition",
            "example" : "{invalidPropertyName=[propertyValue], missingScopes=[scope1, scope2]}"
          },
          "correlationId" : {
            "type" : "string",
            "description" : "A unique identifier for the request. Include this value with any error reports or support tickets",
            "format" : "uuid",
            "example" : "aeb5f871-7f07-4993-9211-075dc63e7cbf"
          },
          "errors" : {
            "type" : "array",
            "description" : "further information about the error",
            "example" : null,
            "items" : {
              "$ref" : "#/components/schemas/ErrorDetail"
            }
          },
          "links" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "string",
              "example" : null
            },
            "description" : "A map of link names to associated URIs containing documentation about the error or recommended remediation steps",
            "example" : null
          },
          "message" : {
            "type" : "string",
            "description" : "A human readable message describing the error along with remediation steps where appropriate",
            "example" : "An error occurred"
          },
          "subCategory" : {
            "type" : "string",
            "description" : "A specific category that contains more specific detail about the error",
            "example" : null
          }
        },
        "example" : {
          "message" : "Invalid input (details will vary based on the error)",
          "correlationId" : "aeb5f871-7f07-4993-9211-075dc63e7cbf",
          "category" : "VALIDATION_ERROR",
          "links" : {
            "knowledge-base" : "https://www.hubspot.com/products/service/knowledge-base"
          }
        }
      },
      "ErrorDetail" : {
        "required" : [ "message" ],
        "type" : "object",
        "properties" : {
          "code" : {
            "type" : "string",
            "description" : "The status code associated with the error detail",
            "example" : null
          },
          "context" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "array",
              "example" : null,
              "items" : {
                "type" : "string",
                "example" : null
              }
            },
            "description" : "Context about the error condition",
            "example" : "{missingScopes=[scope1, scope2]}"
          },
          "in" : {
            "type" : "string",
            "description" : "The name of the field or parameter in which the error was found.",
            "example" : null
          },
          "message" : {
            "type" : "string",
            "description" : "A human readable message describing the error along with remediation steps where appropriate",
            "example" : null
          },
          "subCategory" : {
            "type" : "string",
            "description" : "A specific category that contains more specific detail about the error",
            "example" : null
          }
        },
        "example" : null
      },
      "FileColumn" : {
        "required" : [ "name", "type" ],
        "type" : "object",
        "properties" : {
          "name" : {
            "type" : "string",
            "description" : "The name of the column, represented as a string.",
            "example" : null
          },
          "type" : {
            "type" : "string",
            "description" : "The data type of the column, represented as a string.",
            "example" : null
          }
        },
        "example" : null
      },
      "FileStructureRequest" : {
        "required" : [ "columns", "headerRowIndex", "sheetIndex" ],
        "type" : "object",
        "properties" : {
          "columns" : {
            "type" : "array",
            "description" : "List of columns to pick as datasource.",
            "example" : null,
            "items" : {
              "$ref" : "#/components/schemas/FileColumn"
            }
          },
          "headerRowIndex" : {
            "type" : "integer",
            "description" : "Index of the header row. Starting with 1. Default is: 1",
            "format" : "int32",
            "example" : null
          },
          "sheetIndex" : {
            "type" : "integer",
            "description" : "Index of the sheet. Starting with 0. Default is: 0.\nOnly relevant in case of XLS or XLSX.",
            "format" : "int32",
            "example" : null
          }
        },
        "example" : null
      },
      "JsonDataRequest" : {
        "required" : [ "columns", "data" ],
        "type" : "object",
        "properties" : {
          "columns" : {
            "type" : "array",
            "description" : "Columns of datasource with the type",
            "example" : null,
            "items" : {
              "$ref" : "#/components/schemas/FileColumn"
            }
          },
          "data" : {
            "type" : "array",
            "description" : "Initial data of the datasource",
            "example" : null,
            "items" : {
              "type" : "object",
              "additionalProperties" : {
                "type" : "object",
                "properties" : { },
                "example" : null
              },
              "example" : null
            }
          },
          "recordId" : {
            "type" : "string",
            "description" : "Optional column-name which is used for identifying records of a datasource. This is required for updating single records of a datasource.",
            "example" : null
          }
        },
        "example" : null
      }
    },
    "responses" : {
      "Error" : {
        "description" : "An error occurred.",
        "content" : {
          "*/*" : {
            "schema" : {
              "$ref" : "#/components/schemas/Error"
            },
            "example" : null
          }
        }
      }
    },
    "securitySchemes" : {
      "developer_hapikey" : {
        "type" : "apiKey",
        "name" : "hapikey",
        "in" : "query"
      },
      "oauth2" : {
        "type" : "oauth2",
        "flows" : {
          "authorizationCode" : {
            "authorizationUrl" : "https://app.hubspot.com/oauth/authorize",
            "tokenUrl" : "https://api.hubapi.com/oauth/v1/token",
            "scopes" : {
              "data-integration-json-datasource-read" : "",
              "data-integration-json-datasource-write" : "",
              "data_integration.data_source.file.read" : "",
              "data_integration.data_source.file.write" : ""
            }
          }
        }
      },
      "private_apps" : {
        "type" : "apiKey",
        "name" : "private-app",
        "in" : "header"
      },
      "private_apps_legacy" : {
        "type" : "apiKey",
        "name" : "private-app-legacy",
        "in" : "header"
      }
    }
  },
  "x-hubspot-product-tier-requirements" : {
    "marketing" : "FREE",
    "sales" : "FREE",
    "service" : "FREE",
    "cms" : "FREE",
    "commerce" : "FREE",
    "crmHub" : "FREE",
    "dataHub" : "FREE"
  }
}