# Upload a file directly

Source: https://docs.musicnerd.net/api-reference/vault/upload

Upload a file directly

## POST /api/vault/upload

Full OpenAPI specification: https://docs.musicnerd.net/spec/vault.json

## Authentication

This operation requires one of the security alternatives in the specification below. Security scheme definitions are included where present in the published specification.

[Authentication guide](https://docs.musicnerd.net/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Music Nerd API: vault uploads",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://musicnerd-api.vercel.app",
      "description": "Production"
    },
    {
      "url": "https://musicnerd-api-staging.vercel.app",
      "description": "Staging (staging database)"
    }
  ],
  "paths": {
    "/api/vault/upload": {
      "post": {
        "summary": "Upload a file directly",
        "operationId": "uploadVaultFile",
        "security": [
          {
            "privyBearer": []
          }
        ],
        "description": "Uploads a file to an artist's vault in one request, saves it as an approved source and queues a Lore refresh. Same limits and types as [Sign an upload](/api-reference/vault/sign-upload), which with [Complete an upload](/api-reference/vault/complete-upload) sends the file straight to storage instead of through the API. Not runnable from this page: the body is `multipart/form-data`.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file",
                  "artistId"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "The file, at most 10 MB. Bodies over about 4.5 MB are refused by the platform before reaching the API; use Sign an upload for larger files."
                  },
                  "artistId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "The artist's ID."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The saved source. `warning` is set when the Lore refresh could not be queued or a PDF had no readable text.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "success",
                    "source"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok"
                      ]
                    },
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ],
                      "description": "Always true on 200."
                    },
                    "source": {
                      "$ref": "#/components/schemas/VaultSource"
                    },
                    "warning": {
                      "type": "string",
                      "description": "Advice to show the user. Absent when there is none."
                    }
                  }
                },
                "example": {
                  "status": "ok",
                  "success": true,
                  "source": {
                    "id": "2c6f1c6e-4f0a-4b9b-8a6a-3b1f0b2d9e71",
                    "artistId": "aab92f80-f9e1-4299-aa33-7dd85c8de5d3",
                    "origin": "upload",
                    "activityId": "5d1e3a0c-7b2f-4c8e-9a1d-0e2f3a4b5c6d",
                    "url": "https://example.supabase.co/storage/v1/object/public/vault-files/aab92f80-f9e1-4299-aa33-7dd85c8de5d3/1761069851512_press-kit.pdf",
                    "title": "press-kit.pdf",
                    "snippet": "Bio Ritmo is a ten-piece salsa band from Richmond, Virginia…",
                    "type": "document",
                    "status": "approved",
                    "fileName": "press-kit.pdf",
                    "fileSize": 482133,
                    "filePath": "aab92f80-f9e1-4299-aa33-7dd85c8de5d3/1761069851512_press-kit.pdf",
                    "contentType": "application/pdf",
                    "extractedText": "Bio Ritmo is a ten-piece salsa band from Richmond, Virginia…",
                    "ogImage": null,
                    "podcastEpisodeKey": null,
                    "podcastShowTitle": null,
                    "podcastEpisodeTitle": null,
                    "publishedAt": null,
                    "createdAt": "2026-10-21 18:04:11.512+00",
                    "updatedAt": "2026-10-21 18:04:11.512+00"
                  }
                }
              }
            }
          },
          "400": {
            "description": "`file` or `artistId` is missing, the file is over 10 MB, its type isn't supported, or its leading bytes contradict its type.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "missing": {
                    "summary": "A missing field",
                    "value": {
                      "status": "error",
                      "error": "File and artistId are required"
                    }
                  },
                  "size": {
                    "summary": "Too large",
                    "value": {
                      "status": "error",
                      "error": "File too large: 12.4 MB (maximum 10 MB per file)"
                    }
                  },
                  "type": {
                    "summary": "An unsupported type",
                    "value": {
                      "status": "error",
                      "error": "File type not supported: \"application/zip\". Supported: PDF, TXT, MD, CSV, JSON, DOCX, images, audio."
                    }
                  },
                  "content": {
                    "summary": "The file's bytes contradict its type",
                    "value": {
                      "status": "error",
                      "error": "File content does not match declared type"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "No token, an invalid or expired token, or no Music Nerd user for it (`Not signed in`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "Not signed in"
                }
              }
            }
          },
          "403": {
            "description": "The user is neither the artist's claimant nor an admin, or the artist's claim changed while the upload was in flight.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "notAuthorized": {
                    "summary": "Not the claimant or an admin",
                    "value": {
                      "status": "error",
                      "error": "Not authorized for this artist"
                    }
                  },
                  "ownershipChanged": {
                    "summary": "The claim changed during the upload",
                    "value": {
                      "status": "error",
                      "error": "Artist ownership changed; this operation was cancelled."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Storage refused the file, the save failed, the token could not be checked, or `artistId` isn't a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "storage": {
                    "summary": "Storage refused the file",
                    "value": {
                      "status": "error",
                      "error": "Failed to upload file to storage"
                    }
                  },
                  "save": {
                    "summary": "The save failed",
                    "value": {
                      "status": "error",
                      "error": "Failed to upload file"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "File storage isn't configured on this deployment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "File storage is not configured on this server (missing SUPABASE_URL / SUPABASE_SERVICE_ROLE_KEY)."
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "VaultSource": {
        "type": "object",
        "description": "A row of the artist's vault, as stored.",
        "required": [
          "id",
          "artistId",
          "origin",
          "url",
          "status",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "artistId": {
            "type": "string",
            "format": "uuid"
          },
          "origin": {
            "type": "string",
            "description": "`upload` for a file the claimant or an admin uploaded."
          },
          "activityId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "The activity event that recorded the upload."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The file's public URL in storage."
          },
          "title": {
            "type": [
              "string",
              "null"
            ],
            "description": "The file's name."
          },
          "snippet": {
            "type": [
              "string",
              "null"
            ],
            "description": "The first 300 characters of extracted text, or `Uploaded file: <name>` when there is none."
          },
          "type": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "document",
              "data",
              "image",
              "audio",
              null
            ],
            "description": "`image` and `audio` by MIME type, `data` for CSV and JSON, `document` otherwise."
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "rejected"
            ],
            "description": "Always `approved` for an upload."
          },
          "fileName": {
            "type": [
              "string",
              "null"
            ]
          },
          "fileSize": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Bytes."
          },
          "filePath": {
            "type": [
              "string",
              "null"
            ],
            "description": "The storage key (`<artistId>/<name>`), not the URL."
          },
          "contentType": {
            "type": [
              "string",
              "null"
            ],
            "description": "The resolved MIME type."
          },
          "extractedText": {
            "type": [
              "string",
              "null"
            ],
            "description": "The file's text, for text files and PDFs with readable text."
          },
          "ogImage": {
            "type": [
              "string",
              "null"
            ]
          },
          "podcastEpisodeKey": {
            "type": [
              "string",
              "null"
            ]
          },
          "podcastShowTitle": {
            "type": [
              "string",
              "null"
            ]
          },
          "podcastEpisodeTitle": {
            "type": [
              "string",
              "null"
            ]
          },
          "publishedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "createdAt": {
            "type": "string"
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "status",
          "error"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "privyBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Access token",
        "description": "The signed-in user's access token. Copy it at https://musicnerd.net/access after signing in. The user must be the artist's approved claimant or a Music Nerd admin."
      }
    }
  }
}
```
