> ## Documentation Index > Fetch the complete documentation index at: https://docs.ndi.nace.ai/llms.txt > Use this file to discover all available pages before exploring further. # create_upload > Stage bytes for a single granular operation and return a handle. Cost class: **fast** (upload I/O only; no processing units charged here). The returned ``upload_id`` is passed as ``{"type": "upload", "upload_id": ""}`` in any subsequent document-operation request. Uploads are **single-use**: the bytes are deleted once the job that consumes them finishes, and are never stored against a workspace. The ``expires_at`` field is the hard ceiling — if the upload was never consumed, storage is reclaimed at that time. Uploads are workspace-free: this is the entry point for callers that want to use granular operations without onboarding to the full ingestion model. ## OpenAPI ````yaml /openapi.json post /v1/uploads openapi: 3.1.0 info: description: >- Document intelligence: parse, split, classify, extract, and ground files, or build a searchable workspace. Authenticate with ``X-API-Key``. title: NDI Platform API version: 0.1.0 servers: - url: https://ndi-api.nace.ai security: [] tags: [] paths: /v1/uploads: post: tags: - document-operations summary: create_upload description: >- Stage bytes for a single granular operation and return a handle. Cost class: **fast** (upload I/O only; no processing units charged here). The returned ``upload_id`` is passed as ``{"type": "upload", "upload_id": ""}`` in any subsequent document-operation request. Uploads are **single-use**: the bytes are deleted once the job that consumes them finishes, and are never stored against a workspace. The ``expires_at`` field is the hard ceiling — if the upload was never consumed, storage is reclaimed at that time. Uploads are workspace-free: this is the entry point for callers that want to use granular operations without onboarding to the full ingestion model. operationId: create_upload_v1_uploads_post requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/Body_create_upload_v1_uploads_post' required: true responses: '200': content: application/json: schema: $ref: >- #/components/schemas/ndi_service__app__platform_api__document_operations__schemas__UploadResponse description: Successful Response '504': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Gateway Timeout default: content: application/json: example: error: code: invalid_request detail: null message: >- Request body has extra fields that this operation does not accept. request_id: req-01j9k2n3p4q5r6s7t8v9 retryable: false schema: $ref: '#/components/schemas/ErrorEnvelope' description: >- Typed error envelope used by every 4xx and 5xx. ``error.code`` distinguishes the failure; HTTP status is a consequence of the code. security: - APIKeyHeader: [] components: schemas: Body_create_upload_v1_uploads_post: properties: file: contentMediaType: application/octet-stream description: The document to stage for a granular operation. title: File type: string ttl_seconds: anyOf: - maximum: 604800 minimum: 1 type: integer - type: 'null' description: >- How long this upload is retained (seconds). Capped at MAX_UPLOAD_TTL_SECONDS. Defaults to DEFAULT_UPLOAD_TTL_SECONDS. Bytes are deleted at job completion, so the TTL is only the ceiling for an upload that was never consumed. title: Ttl Seconds required: - file title: Body_create_upload_v1_uploads_post type: object ndi_service__app__platform_api__document_operations__schemas__UploadResponse: additionalProperties: false description: >- Returned by ``POST /v1/uploads`` on success. ``upload_id`` is the handle passed to :class:`~ndi_service.app.platform_api.contracts.UploadSource`. Bytes are deleted at job completion, not at ``expires_at``; the TTL is the ceiling for an upload that was never consumed. properties: content_hash: title: Content Hash type: string expires_at: format: date-time title: Expires At type: string file_name: title: File Name type: string size_bytes: title: Size Bytes type: integer upload_id: format: uuid title: Upload Id type: string required: - upload_id - file_name - size_bytes - content_hash - expires_at title: UploadResponse type: object ErrorEnvelope: description: Every non-2xx body on ``/v1``. example: error: code: invalid_request detail: null message: Request body has extra fields that this operation does not accept. request_id: req-01j9k2n3p4q5r6s7t8v9 retryable: false properties: error: $ref: '#/components/schemas/Error' required: - error title: ErrorEnvelope type: object Error: description: The error object, per spec 12 §1.8. properties: code: $ref: '#/components/schemas/ErrorCode' detail: anyOf: - additionalProperties: true type: object - type: 'null' description: Structured payload, when the code carries one. title: Detail message: description: Human- and model-readable; says what to do differently. title: Message type: string request_id: description: Per-request correlation id; matches the ``X-Request-Id`` header. title: Request Id type: string retryable: description: Whether retrying the identical request could succeed. title: Retryable type: boolean required: - code - message - retryable - request_id title: Error type: object ErrorCode: description: |- Every error the ``/v1`` surface can return. Clients must treat this as an **open** enum: a new member is an additive change (spec 12 §9), and a client that crashes on an unknown code makes every future error a breaking change. enum: - invalid_request - unsupported_file_type - file_too_large - invalid_schema - invalid_sql - invalid_path_prefix - command_not_permitted - batch_too_large - domain_validation_failed - default_label_required - wait_required_for_zero_retention - workspace_not_found - file_not_found - job_not_found - upload_not_found - node_not_found - schema_not_found - domain_not_found - session_not_found - access_label_not_found - path_conflict - schema_version_conflict - access_label_name_taken - workspace_name_taken - access_label_in_use - upload_expired - file_not_ingested - workspace_deleting - workspace_not_deletable - ingestion_in_progress - job_not_cancellable - confirmation_required - domain_not_published - domain_in_use - reserved_domain_slug - kg_not_built - kg_build_in_progress - session_busy - range_not_satisfiable - result_expired - access_denied - access_backstop_violation - access_mode_not_implemented - rate_limited - concurrency_limit_reached - quota_exceeded - corrupt_file - zero_byte_file - encrypted_file - parse_failed - ocr_failed - conversion_failed - sheetless_workbook - unplayable_media - unclassified_pages - job_cancelled - job_timeout - upstream_unavailable - internal_error - unauthorized - not_implemented title: ErrorCode type: string securitySchemes: APIKeyHeader: in: header name: X-API-Key type: apiKey ````