Trouble with file assets in Sanity Studio and how to upload them

I can see the confusion! The docs you quoted are about the HTTP API endpoint for uploading files, but to actually use files in your Studio, you need to define a file field type in your schema. The fileAsset you're seeing in GraphQL is the underlying asset type, but without a proper schema field, you won't see it in Studio.

Here's what you need to do:

Add a File Field to Your Schema

In your document schema, add a field with type: 'file':

{
  name: 'myDocument',
  type: 'document',
  fields: [
    {
      name: 'title',
      type: 'string',
    },
    {
      name: 'attachment',  // or whatever you want to call it
      title: 'Attachment',
      type: 'file',  // This is the key!
    }
  ]
}

Once you add this to your schema and restart your Studio, you'll see an upload interface where you can drag-and-drop or select files (PDFs, ZIPs, etc.).

Querying Files

When you query your documents, you can access the file like this:

*[_type == "myDocument"] {
  title,
  "fileUrl": attachment.asset->url
}

The file field type documentation has more details on available properties and options.

Why You're Seeing It in GraphQL But Not Studio

The sanity.fileAsset type exists in GraphQL because it's a system type that stores uploaded files, but it's not meant to be edited directly in Studio. You access file assets through file type fields in your documents, similar to how you use image type fields to work with sanity.imageAsset.

Once you add the file field to your schema, you'll be able to upload files through Studio, and they'll automatically create the underlying fileAsset documents that you're currently seeing in GraphQL.