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

# Create a staged upload

> Returns a documentId and a signed uploadUrl. PUT the file bytes to uploadUrl, then create a job with `source.type: "document"` and the documentId.



## OpenAPI

````yaml /openapi.json post /api/v1/uploads
openapi: 3.1.0
info:
  title: AnythingMD API
  version: 1.0.0-preview
  description: >-
    Convert PDFs, Office documents, spreadsheets and images into Markdown.
    Guides, pricing and limits: https://docs.anythingmd.com. Preview: available
    to workspaces that have purchased credits.
servers:
  - url: https://anythingmd.com
    description: Production
security:
  - BearerAuth: []
tags:
  - name: Uploads
    description: Stage a source document for conversion
  - name: Jobs
    description: Create and observe async conversion work
  - name: Artifacts
    description: Retrieve job outputs
  - name: Quotes
    description: See what a conversion would cost before starting it.
  - name: Receipts
    description: What a job was charged. Receipts outlive the job.
paths:
  /api/v1/uploads:
    post:
      tags:
        - Uploads
      summary: Create a staged upload
      description: >-
        Returns a documentId and a signed uploadUrl. PUT the file bytes to
        uploadUrl, then create a job with `source.type: "document"` and the
        documentId.
      operationId: createUpload
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            minLength: 1
          description: >-
            If reused within the retention window, replay the original result
            instead of a second mutation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUploadRequest'
      responses:
        '200':
          description: Existing upload slot returned for a replayed idempotency key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUploadResponse'
        '201':
          description: Upload slot created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUploadResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: >-
            Authenticated, but the credential lacks the scope this operation
            requires (code: insufficient_scope). Reads need documents:read,
            uploads and job creation need documents:write, cancel needs
            documents:delete. Checked before the resource is looked up, so this
            never reveals whether the resource exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
        - BearerAuth: []
components:
  schemas:
    CreateUploadRequest:
      type: object
      properties:
        fileName:
          type: string
          minLength: 1
          description: Original file name used for the object key and metadata
        fileType:
          type: string
          minLength: 1
          description: MIME type of the file being uploaded
        idempotencyKey:
          description: >-
            If the same key is reused within the idempotency window, return the
            original upload slot instead of creating a duplicate
          type: string
          minLength: 1
        content_hash:
          description: Optional SHA-256 payload checksum (e.g. sha256:<hex>)
          type: string
          minLength: 1
        contentHash:
          description: Alias for content_hash
          type: string
          minLength: 1
      required:
        - fileName
        - fileType
      additionalProperties: false
    CreateUploadResponse:
      type: object
      properties:
        documentId:
          type: string
          minLength: 1
          description: Id of an uploaded source document
        uploadUrl:
          type: string
          description: Pre-signed URL for HTTP PUT of the file bytes
        accessUrl:
          type: string
          description: Object URL the conversion worker will read after upload
        objectKey:
          type: string
          description: Storage object key for the uploaded file
        expiresAt:
          description: ISO-8601 expiry of the pre-signed upload URL, if known
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
      required:
        - documentId
        - uploadUrl
        - accessUrl
        - objectKey
      additionalProperties: false
    ApiError:
      type: object
      properties:
        error:
          type: string
          description: User-facing error message
        code:
          description: Optional machine-readable error code (e.g. invalid_request)
          type: string
      required:
        - error
      additionalProperties: false
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: >-
        Create a key under Settings → API Keys and send it as `Authorization:
        Bearer amd_live_…`. See https://docs.anythingmd.com/authentication.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.