{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/signatureapi-com/json-schema/signatureapi-com-upload-upload-schema.json",
  "title": "Upload.Upload",
  "description": "An **upload** is a file stored in SignatureAPI that can be used as a document source in an envelope.\n\nUploads support two file formats: **PDF** and **DOCX**. The maximum file size is 5 MB.\n\n### Retention\n\nUploads have one of two retention types:\n\n- **Temporary** -- Created through the API. Automatically deleted after 24 hours. Best for one-time use.\n- **Permanent** -- Created through the dashboard library. Stored indefinitely and reusable across multiple envelopes. Identified by a unique `key`.\n\n### Usage\n\nAfter uploading a file, use the returned `url` value as the document source when creating an envelope. This URL is an internal reference and cannot be used to download the file directly.\n\n### Structure\n\nUse the **Get Upload Structure** endpoint to inspect the internal structure of an uploaded file. The structure includes page dimensions, detected **placeholders**, and -- for DOCX templates -- detected **template fields**.\n",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/signatureapi-com-uploads-api-openapi.yml#/components/schemas/Upload.Upload",
  "x-schema-role": "model",
  "x-schema-direction": "output",
  "oneOf": [
    {
      "$ref": "#/$defs/Upload.TemporaryUpload"
    },
    {
      "$ref": "#/$defs/Upload.PermanentUpload"
    }
  ],
  "$defs": {
    "Upload.CreatedAt": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "title": "Created At",
      "description": "The date and time when the upload was created, in ISO 8601 format.",
      "type": "string",
      "format": "date-time"
    },
    "Upload.ExpiresAt": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "title": "Expires At",
      "description": "The date and time when the temporary upload expires and is automatically deleted, in ISO 8601 format. Only present on temporary uploads. The expiration is 24 hours after creation.\n",
      "type": "string",
      "format": "date-time"
    },
    "Upload.Format": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "type": "string",
      "title": "Format",
      "description": "The file format of the upload.\n\n- `pdf` -- A PDF file (`application/pdf`).\n- `docx` -- A DOCX file (`application/vnd.openxmlformats-officedocument.wordprocessingml.document`).\n- `png` -- A PNG image (`image/png`).\n",
      "enum": [
        "pdf",
        "docx",
        "png"
      ]
    },
    "Upload.Id": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "type": "string",
      "title": "Upload ID",
      "description": "The unique identifier of the upload."
    },
    "Upload.Key": {
      "x-schema-role": "property",
      "x-schema-direction": "any",
      "title": "Upload Key",
      "description": "A unique key that identifies the permanent upload within your account. Only lowercase letters, numbers, hyphens, and underscores are allowed. Maximum 100 characters.\n",
      "pattern": "^[a-z0-9_-]+$",
      "maxLength": 100,
      "type": "string"
    },
    "Upload.PermanentUpload": {
      "x-schema-role": "model",
      "x-schema-direction": "output",
      "title": "Permanent Upload",
      "description": "A permanent upload stored in SignatureAPI indefinitely. Permanent uploads are created through the dashboard library and can be reused across multiple envelopes. Each permanent upload has a unique `key` for identification.\n",
      "type": "object",
      "properties": {
        "id": {
          "$ref": "#/$defs/Upload.Id"
        },
        "retention": {
          "allOf": [
            {
              "$ref": "#/$defs/Upload.Retention"
            },
            {
              "const": "permanent"
            }
          ]
        },
        "key": {
          "$ref": "#/$defs/Upload.Key"
        },
        "url": {
          "$ref": "#/$defs/Upload.Url"
        },
        "sha_256": {
          "$ref": "#/$defs/Upload.Sha256"
        },
        "size": {
          "$ref": "#/$defs/Upload.Size"
        },
        "format": {
          "$ref": "#/$defs/Upload.Format"
        },
        "created_at": {
          "$ref": "#/$defs/Upload.CreatedAt"
        }
      },
      "required": [
        "id",
        "retention",
        "key",
        "url",
        "sha_256",
        "size",
        "format",
        "created_at"
      ]
    },
    "Upload.Retention": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "title": "Retention",
      "description": "The retention type of the upload.\n\n- `temporary` -- The file is automatically deleted after 24 hours. Created through the API.\n- `permanent` -- The file is stored indefinitely. Created through the dashboard library.\n",
      "type": "string",
      "enum": [
        "temporary",
        "permanent"
      ]
    },
    "Upload.Sha256": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "title": "SHA-256 Hash",
      "description": "The SHA-256 hash of the uploaded file in hexadecimal format.",
      "type": "string"
    },
    "Upload.Size": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "title": "Size",
      "description": "The size of the uploaded file in bytes. Maximum 5 MB (5,242,880 bytes).",
      "type": "integer"
    },
    "Upload.TemporaryUpload": {
      "x-schema-role": "model",
      "x-schema-direction": "output",
      "title": "Temporary Upload",
      "description": "A temporary upload stored in SignatureAPI for 24 hours. Temporary uploads are created through the API and automatically deleted when they expire. Best for one-time use when creating an envelope.\n",
      "type": "object",
      "properties": {
        "id": {
          "$ref": "#/$defs/Upload.Id"
        },
        "retention": {
          "allOf": [
            {
              "$ref": "#/$defs/Upload.Retention"
            },
            {
              "const": "temporary"
            }
          ]
        },
        "url": {
          "$ref": "#/$defs/Upload.Url"
        },
        "sha_256": {
          "$ref": "#/$defs/Upload.Sha256"
        },
        "size": {
          "$ref": "#/$defs/Upload.Size"
        },
        "format": {
          "$ref": "#/$defs/Upload.Format"
        },
        "created_at": {
          "$ref": "#/$defs/Upload.CreatedAt"
        },
        "expires_at": {
          "$ref": "#/$defs/Upload.ExpiresAt"
        }
      },
      "required": [
        "id",
        "retention",
        "url",
        "sha_256",
        "size",
        "format",
        "created_at",
        "expires_at"
      ]
    },
    "Upload.Url": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "title": "URL",
      "description": "A URL used to reference the uploaded file.\n\nThis internal URL can be used as input in other fields, like `document.url`.\n\nThe file's content cannot be retrieved directly via this URL.\n",
      "type": "string",
      "format": "uri"
    }
  }
}