---
updatedAt: 2025-10-12T09:55:26.000Z
agentTools:
  projectIndex: https://api-spreadsheet-docs.readme.io/llms.txt
---

# Create a CSV file from JSON data

Creates a new CSV file in your API Spreadsheets account from provided JSON data. Supports record-style rows or matrix data with column names.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "API Spreadsheets — Utilities",
    "version": "1.0.0",
    "description": "Utility endpoints to create API files from JSON data, generate downloadable files, and list/manage existing files."
  },
  "servers": [
    {
      "url": "https://api.apispreadsheets.com"
    }
  ],
  "paths": {
    "/utilities/create": {
      "post": {
        "operationId": "utilitiesCreate",
        "summary": "Create a CSV file from JSON data",
        "description": "Creates a new CSV file in your API Spreadsheets account from provided JSON data. Supports record-style rows or matrix data with column names.",
        "parameters": [
          {
            "name": "AccessKey",
            "in": "header",
            "required": true,
            "description": "Account access key.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "SecretKey",
            "in": "header",
            "required": true,
            "description": "Account secret key.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateOrDownloadRequest"
              },
              "examples": {
                "records": {
                  "summary": "Records format",
                  "value": {
                    "fileName": "customers",
                    "data": [
                      {
                        "id": 1,
                        "name": "Alice",
                        "amount": 19.99
                      },
                      {
                        "id": 2,
                        "name": "Bob",
                        "amount": 42.5
                      }
                    ]
                  }
                },
                "matrix": {
                  "summary": "Matrix format (requires columnNames)",
                  "value": {
                    "fileName": "customers_matrix",
                    "columnNames": [
                      "id",
                      "name",
                      "amount"
                    ],
                    "data": [
                      [
                        1,
                        "Alice",
                        19.99
                      ],
                      [
                        2,
                        "Bob",
                        42.5
                      ]
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "File created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateFileResult"
                }
              }
            }
          },
          "400": {
            "description": "Missing/invalid body or matrix data without columnNames.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingData": {
                    "value": {
                      "error": "Missing 'data' parameter in request"
                    }
                  },
                  "badFormat": {
                    "value": {
                      "error": "Your 'data' is not in a valid format. Please visit www.apispreadsheets.com/utilities to see examples of proper data formats"
                    }
                  },
                  "matrixNeedsColumns": {
                    "value": {
                      "error": "For the 'matrix' data format, you need to include 'columnNames' parameter. Please visit www.apispreadsheets.com/utilities to see examples of proper data formats"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid AccessKey/SecretKey, or blocked by security settings/domain whitelist.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingHeaders": {
                    "value": {
                      "error": "AccessKey and SecretKey headers required"
                    }
                  },
                  "invalidKeys": {
                    "value": {
                      "error": "Your account keys are invalid to access this API"
                    }
                  },
                  "blocked": {
                    "value": {
                      "error": "Either your 'accessKey' parameter and/or 'secretKey' parameter is missing. Or the keys are invalid. Or you have set up domain whitelist and you are requesting from another domain."
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Plan restrictions / over quota / per-file row limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "noAccess": {
                    "value": {
                      "error": "Your plan does not allow access to this API. Please upgrade to a higher payment plan"
                    }
                  },
                  "overLimit": {
                    "value": {
                      "error": "You are over your API requests limit. Please upgrade to a higher payment plan"
                    }
                  },
                  "rowsExceeded": {
                    "value": {
                      "error": "Your data is 1000 rows. Your rows per file limit is 250. Please upgrade to a higher payment plan"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error creating the file.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "generic": {
                    "value": {
                      "error": "There was an error creating your file. This maybe due to your data being corrupted or maybe on our end. Try again, and contact support through your dashboard if the error persists."
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CreateOrDownloadRequest": {
        "type": "object",
        "description": "Payload for create/download: either an array of record objects OR a matrix (array of arrays) with top-level columnNames.",
        "properties": {
          "fileName": {
            "type": "string",
            "description": "Optional display name for the file; defaults to a timestamp."
          },
          "data": {
            "description": "Rows to import.",
            "oneOf": [
              {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                },
                "description": "Record rows (array of objects)."
              },
              {
                "type": "array",
                "items": {
                  "type": "array",
                  "items": {}
                },
                "description": "Matrix rows (array of arrays). When using this format, provide 'columnNames' at the top level."
              }
            ]
          },
          "columnNames": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Required when using matrix format (array of arrays)."
          }
        },
        "required": [
          "data"
        ],
        "additionalProperties": false
      },
      "CreateFileResult": {
        "type": "object",
        "description": "Result from creating the API file.",
        "properties": {
          "name": {
            "type": "string"
          },
          "size": {
            "type": "integer",
            "format": "int64"
          },
          "columnNames": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sampleData": {
            "type": "array",
            "items": {
              "type": "array",
              "items": {}
            },
            "description": "First 5 rows (matrix)."
          },
          "colLen": {
            "type": "integer"
          },
          "rowLen": {
            "type": "integer"
          },
          "fileID": {
            "type": "string",
            "description": "Public file hash/ID."
          },
          "createdDt": {
            "type": "string"
          },
          "apiGetUrl": {
            "type": "string",
            "format": "uri"
          },
          "apiPostUrl": {
            "type": "string",
            "format": "uri"
          },
          "dashboardUrl": {
            "type": "string",
            "format": "uri"
          },
          "isPrivate": {
            "type": "boolean"
          },
          "accessKey": {
            "type": "string",
            "nullable": true
          },
          "secretKey": {
            "type": "string",
            "nullable": true
          },
          "inputType": {
            "type": "string"
          }
        },
        "additionalProperties": true,
        "required": [
          "name",
          "size",
          "columnNames",
          "colLen",
          "rowLen",
          "fileID",
          "createdDt",
          "apiGetUrl",
          "apiPostUrl",
          "dashboardUrl",
          "isPrivate"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}
```