> ## Documentation Index
> Fetch the complete documentation index at: https://docs.woodwide.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Prepare Signed-URL Upload

> Get a signed URL for uploading a large dataset file.

Upload the file directly to the returned signed URL, then call `POST /datasets/{dataset_version_id}/complete` to trigger ingestion.

Supports an `Idempotency-Key` header to safely retry requests.


## OpenAPI

````yaml /openapi.json post /datasets/upload
openapi: 3.1.0
info:
  title: Woodwide API
  description: API service for the Woodwide platform
  version: 0.1.0
servers:
  - url: https://api.woodwide.ai
    description: Production
security: []
paths:
  /datasets/upload:
    post:
      tags:
        - Datasets
      summary: Prepare Signed-URL Upload
      description: Get a signed URL for uploading a large dataset file.
      operationId: prepare_dataset_upload_datasets_upload_post
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Idempotency-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatasetUploadPrepareRequest'
            example:
              dataset_name: large_dataset
              file:
                filename: large_data.csv
                bytes: 50000000
                content_type: text/csv
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetUploadPrepareResponse'
              example:
                dataset:
                  id: a1b2c3d4-0000-0000-0000-000000000001
                  version_id: a1b2c3d4-0000-0000-0000-000000000002
                  version_number: 1
                job_id: a1b2c3d4-0000-0000-0000-000000000003
                upload:
                  filename: large_data.csv
                  bytes: 50000000
                  content_type: text/csv
                  upload_url: https://storage.example.com/upload?signature=...
        '401':
          description: Unauthorized -- API key is missing or invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: Not authenticated
        '403':
          description: >-
            Forbidden -- your API key does not have permission for this
            resource.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: Forbidden
        '404':
          description: Not Found -- the requested resource does not exist.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: >-
            Too Many Requests -- you have exceeded the rate limit. Heavy
            operations (training, inference, dataset uploads) are limited to 60
            requests per minute per API key. All other endpoints are limited to
            600 requests per minute per API key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: Rate limit exceeded. Retry after a short delay.
      security:
        - HTTPBearer: []
components:
  schemas:
    DatasetUploadPrepareRequest:
      properties:
        dataset_name:
          type: string
          title: Dataset Name
        dataset_id:
          type: string
          format: uuid
          title: Dataset Id
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        override:
          type: boolean
          title: Override
          description: >-
            When `true`, replaces the data in the current version instead of
            creating a new version. Defaults to `false`.
          default: false
        file:
          $ref: '#/components/schemas/DatasetUploadFile'
      type: object
      required:
        - file
      title: DatasetUploadPrepareRequest
      description: Request to prepare a signed-URL dataset upload.
    DatasetUploadPrepareResponse:
      properties:
        dataset:
          $ref: '#/components/schemas/DatasetVersionRef'
        job_id:
          type: string
          format: uuid
          title: Job Id
        upload:
          $ref: '#/components/schemas/DatasetUploadTarget'
      type: object
      required:
        - dataset
        - job_id
        - upload
      title: DatasetUploadPrepareResponse
      description: Response with signed upload URL.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
      description: Returned when request parameters or body fail validation.
    DatasetUploadFile:
      properties:
        filename:
          type: string
          title: Filename
        bytes:
          type: integer
          title: Bytes
          description: File size in bytes.
        content_type:
          type: string
          title: Content Type
      type: object
      required:
        - filename
        - bytes
        - content_type
      title: DatasetUploadFile
      description: File metadata for signed-URL upload.
    DatasetVersionRef:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        version_id:
          type: string
          format: uuid
          title: Version Id
        version_number:
          type: integer
          title: Version Number
      type: object
      required:
        - id
        - version_id
        - version_number
      title: DatasetVersionRef
      description: Dataset version reference.
    DatasetUploadTarget:
      properties:
        filename:
          type: string
          title: Filename
        bytes:
          type: integer
          title: Bytes
        content_type:
          type: string
          title: Content Type
        upload_url:
          type: string
          title: Upload Url
          description: Signed URL to upload the file to.
      type: object
      required:
        - filename
        - bytes
        - content_type
        - upload_url
      title: DatasetUploadTarget
      description: Target for signed-URL upload.
    ValidationError:
      type: object
      required:
        - loc
        - msg
        - type
      properties:
        loc:
          type: array
          items:
            type: string
          title: Location
          description: Path to the field that caused the error.
        msg:
          type: string
          title: Message
          description: Human-readable error message.
        type:
          type: string
          title: Error Type
          description: Machine-readable error type identifier.
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````