---
updatedAt: 2026-10-02T14:01:47.000Z
agentTools:
  projectIndex: https://docs.pennsieve.io/llms.txt
---

# Request an archive

Starts building an archive of the given packages (or of specific files
within them) in one dataset. Files that failed the malware scan are
left out and listed in `BLOCKED_FILES.txt`.


# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "version": "1.0",
    "title": "Downloads API",
    "description": "Asynchronous archive downloads. Request an archive of a selection of\npackages or files, poll it until it is READY, then fetch a short-lived\ndownload link. Archives expire after the retention period (3 days by\ndefault).\n",
    "contact": {
      "name": "Pennsieve Support",
      "email": "support@pennsieve.io"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "servers": [
    {
      "url": "https://api2.pennsieve.io/downloads",
      "description": "Production server"
    },
    {
      "url": "https://api2.pennsieve.net/downloads",
      "description": "Development server"
    }
  ],
  "tags": [
    {
      "name": "Archive",
      "description": "Zip archives of a selection, built in the background."
    }
  ],
  "paths": {
    "/archives": {
      "post": {
        "summary": "Request an archive",
        "description": "Starts building an archive of the given packages (or of specific files\nwithin them) in one dataset. Files that failed the malware scan are\nleft out and listed in `BLOCKED_FILES.txt`.\n",
        "operationId": "createArchive",
        "tags": [
          "Archive"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/DatasetId"
          }
        ],
        "security": [
          {
            "token_dataset_auth": []
          }
        ],
        "x-amazon-apigateway-integration": {
          "$ref": "#/components/x-amazon-apigateway-integrations/download-service"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateArchiveRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The archive is queued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Archive"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "413": {
            "description": "The selection is over the size or file-count limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "x-amazon-apigateway-integrations": {
      "download-service": {
        "type": "aws_proxy",
        "uri": "${api_lambda_arn}",
        "httpMethod": "POST",
        "passthroughBehavior": "when_no_match",
        "contentHandling": "CONVERT_TO_TEXT",
        "payloadFormatVersion": 2
      }
    },
    "securitySchemes": {
      "token_dataset_auth": {
        "type": "apiKey",
        "name": "Authorization",
        "in": "header",
        "x-amazon-apigateway-authorizer": {
          "identitySource": "$request.header.Authorization,$request.querystring.dataset_id",
          "authorizerUri": "${authorize_lambda_invoke_uri}",
          "authorizerPayloadFormatVersion": "2.0",
          "authorizerResultTtlInSeconds": 300,
          "type": "request",
          "enableSimpleResponses": true,
          "authorizerCredentials": "${gateway_authorizer_role}"
        }
      }
    },
    "parameters": {
      "DatasetId": {
        "name": "dataset_id",
        "in": "query",
        "required": true,
        "description": "The dataset the selection belongs to (node id).",
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "Error": {
        "description": "Error.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "CreateArchiveRequest": {
        "type": "object",
        "required": [
          "nodeIds"
        ],
        "properties": {
          "nodeIds": {
            "type": "array",
            "maxItems": 1000,
            "items": {
              "type": "string"
            },
            "description": "Package or folder node ids."
          },
          "archiveName": {
            "type": "string",
            "description": "File name for the archive; `.zip` is added when missing."
          },
          "notify": {
            "type": "string",
            "enum": [
              "auto",
              "email",
              "none"
            ],
            "default": "auto",
            "description": "When to email you the outcome. `auto` emails only if you weren't\nwatching when it finished: you hadn't asked for or polled the\narchive in the 30 seconds before, so an archive ready almost at\nonce sends none; `email` always; `none` never.\n"
          }
        }
      },
      "Archive": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "datasetNodeId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "QUEUED",
              "RUNNING",
              "READY",
              "FAILED",
              "CANCELLED"
            ]
          },
          "archiveName": {
            "type": "string"
          },
          "notify": {
            "type": "string",
            "enum": [
              "auto",
              "email",
              "none"
            ]
          },
          "fileCount": {
            "type": "integer"
          },
          "totalBytes": {
            "type": "integer",
            "format": "int64"
          },
          "blockedCount": {
            "type": "integer",
            "description": "Files left out because they did not pass the malware scan."
          },
          "filesDone": {
            "type": "integer"
          },
          "bytesDone": {
            "type": "integer",
            "format": "int64"
          },
          "archiveBytes": {
            "type": "integer",
            "format": "int64"
          },
          "error": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "readyAt": {
            "type": "string",
            "format": "date-time"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```