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

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# Subir archivos

> Sube archivos a través de la API con una URL prefirmada y luego adjúntalos a recursos de Whop.

Sube archivos a Whop para usarlos en cursos, foros, perfiles, disputas y más.

## Cómo funcionan las subidas

La subida es un flujo de dos pasos, y el SDK ayuda con el primero:

1. **Crea un registro de archivo.** `files.create` devuelve el `id` del nuevo archivo, además de una `upload_url` prefirmada y los `upload_headers` que debes enviar con ella.
2. **Envía los bytes tú mismo.** Haz un `PUT` del contenido del archivo a `upload_url` con esos encabezados. El SDK no transfiere los bytes por ti.

Una vez que llegan los bytes, el archivo se procesa y su `upload_status` pasa a `ready`. Usa `files.retrieve` para consultar periódicamente hasta que esté en `ready` y, después, adjunta el `id` a un recurso y lee la `url` final.

Para subir directamente desde el navegador sin que los bytes pasen por tu servidor, o para enviar un archivo grande por partes, consulta [Subir archivos directamente](https://docs.whop.com/es/developer/guides/direct-file-uploads.md).

## Inicializar el SDK

```typescript TypeScript theme={null}
import { WhopClient } from "@whop/sdk";

const client = new WhopClient({
  token: process.env.WHOP_API_KEY,
});
```

```python Python theme={null}
import os
from whop_sdk import Whop

client = Whop(
    token=os.environ["WHOP_API_KEY"],
)
```

```ruby Ruby theme={null}
require "whop_sdk"

client = Whop_sdk::Client.new(
  token: ENV.fetch("WHOP_API_KEY"),
)
```

```go Go theme={null}
import (
  "context"
  "os"

  whopsdk "github.com/whopio/whopsdk-go/v2"
  whopclient "github.com/whopio/whopsdk-go/v2/client"
  "github.com/whopio/whopsdk-go/v2/option"
)

client := whopclient.NewWhop(
  option.WithToken(os.Getenv("WHOP_API_KEY")),
)
```

```rust Rust theme={null}
use whop_sdk::prelude::*;

let config = ClientConfig {
    token: Some(std::env::var("WHOP_API_KEY").expect("WHOP_API_KEY is not set")),
    ..Default::default()
};
let client = Whop::new(config).expect("Failed to build client");
```

## Subir un archivo

Crea el registro y luego haz un `PUT` de los bytes a la URL prefirmada que se devuelve.

```typescript TypeScript theme={null}
import { readFile } from "node:fs/promises";

// 1. Create the file record and get a presigned upload URL
const file = await client.files.create({ filename: "photo.jpg" });

// 2. Send the bytes to storage yourself
const bytes = await readFile("./photo.jpg");
await fetch(file.upload_url!, {
  method: "PUT",
  headers: file.upload_headers as Record<string, string>,
  body: bytes,
});

console.log(file.id); // file_xxxxxxxxxxxxx — attach it once it's ready
```

```python Python theme={null}
import requests

# 1. Create the file record and get a presigned upload URL
file = client.files.create(filename="photo.jpg")

# 2. Send the bytes to storage yourself
with open("./photo.jpg", "rb") as contents:
    requests.put(
        file.upload_url,
        headers=file.upload_headers or {},
        data=contents,
    )

print(file.id)  # file_xxxxxxxxxxxxx — attach it once it's ready
```

```ruby Ruby theme={null}
require "net/http"

# 1. Create the file record and get a presigned upload URL
file = client.files.create(filename: "photo.jpg")

# 2. Send the bytes to storage yourself
uri = URI(file.upload_url)
request = Net::HTTP::Put.new(uri)
(file.upload_headers || {}).each { |key, value| request[key] = value }
request.body = File.binread("./photo.jpg")
Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

puts file.id # file_xxxxxxxxxxxxx — attach it once it's ready
```

```go Go theme={null}
import (
  "bytes"
  "fmt"
  "net/http"
  "os"
)

// 1. Create the file record and get a presigned upload URL
file, err := client.Files.Create(context.TODO(), &whopsdk.CreateFilesRequest{
  Filename: "photo.jpg",
})
if err != nil {
  return err
}

// 2. Send the bytes to storage yourself
data, err := os.ReadFile("./photo.jpg")
if err != nil {
  return err
}
request, err := http.NewRequest(http.MethodPut, *file.UploadURL, bytes.NewReader(data))
if err != nil {
  return err
}
for key, value := range file.UploadHeaders {
  request.Header.Set(key, fmt.Sprint(value))
}
if _, err := http.DefaultClient.Do(request); err != nil {
  return err
}

fmt.Println(file.ID) // file_xxxxxxxxxxxxx — attach it once it's ready
```

```rust Rust theme={null}
// 1. Create the file record and get a presigned upload URL
let file = client
    .files
    .create(
        &CreateFilesRequest {
            filename: "photo.jpg".to_string(),
            ..Default::default()
        },
        None,
    )
    .await?;

// 2. Send the bytes to storage yourself
let contents = std::fs::read("./photo.jpg")?;
let mut request = reqwest::Client::new()
    .put(file.upload_url.as_deref().unwrap())
    .body(contents);
if let Some(headers) = &file.upload_headers {
    for (key, value) in headers {
        if let Some(value) = value.as_str() {
            request = request.header(key, value);
        }
    }
}
request.send().await?;

println!("{}", file.id); // file_xxxxxxxxxxxxx — attach it once it's ready
```

## Archivos públicos y privados

Cada archivo que subes tiene una **visibilidad** que controla el acceso. Eliges la visibilidad en el momento de la subida y no puedes cambiarla después.

| Visibilidad | Tipo de URL | Quién puede acceder | Uso |
| - | - | - | - |
| `private` (predeterminado) | URL firmada que caduca | Solo tu app, a través de la API | Adjuntos de mensajes, documentos subidos por usuarios, contenido sensible, archivos generados por IA |
| `public` | URL de red de distribución de contenido permanente y sin firmar | Cualquiera que tenga el enlace | Imágenes de productos, miniaturas, branding, recursos de marketing |

> [!WARNING]
>
> **Establece la visibilidad antes de subir.** Los archivos públicos se almacenan en caché en la CDN de Whop y cualquiera que tenga la URL puede acceder a ellos; no hay forma de revocar el acceso. Si el contenido es específico de un usuario o sensible, mantén el valor predeterminado `private`.

### Subir un archivo público

Pasa una visibilidad `public` al crear el archivo y luego sube los bytes de la misma forma:

```typescript TypeScript theme={null}
const file = await client.files.create({
  filename: "product-cover.jpg",
  visibility: "public",
});

// PUT the bytes to file.upload_url, then file.url is a permanent CDN URL
```

```python Python theme={null}
file = client.files.create(
    filename="product-cover.jpg",
    visibility="public",
)

# PUT the bytes to file.upload_url, then file.url is a permanent CDN URL
```

```ruby Ruby theme={null}
file = client.files.create(
  filename: "product-cover.jpg",
  visibility: "public",
)

# PUT the bytes to file.upload_url, then file.url is a permanent CDN URL
```

```go Go theme={null}
file, err := client.Files.Create(context.TODO(), &whopsdk.CreateFilesRequest{
  Filename:   "product-cover.jpg",
  Visibility: whopsdk.CreateFilesRequestVisibilityPublic.Ptr(),
})

// PUT the bytes to file.UploadURL, then file.URL is a permanent CDN URL
```

```rust Rust theme={null}
let file = client
    .files
    .create(
        &CreateFilesRequest {
            filename: "product-cover.jpg".to_string(),
            visibility: Some(CreateFilesRequestVisibility::Public),
            ..Default::default()
        },
        None,
    )
    .await?;

// PUT the bytes to file.upload_url, then file.url is a permanent CDN URL
```

Adjuntar un archivo a un recurso lo mueve al almacenamiento que corresponde a la visibilidad propia de ese recurso. Una `visibility` explícita importa sobre todo para los archivos que enlazas directamente sin adjuntarlos.

### Confirmar que la subida ha terminado

Después de que lleguen los bytes, el archivo se procesa de forma asíncrona. Obtenlo hasta que `upload_status` deje de ser `pending` y `processing`. Cuando sea `ready`, lee la `url` final. Cuando sea `failed`, detente y muestra el error.

```typescript TypeScript theme={null}
let uploaded = await client.files.retrieve({ id: file.id });

while (uploaded.upload_status === "pending" || uploaded.upload_status === "processing") {
  await new Promise((resolve) => setTimeout(resolve, 1000));
  uploaded = await client.files.retrieve({ id: file.id });
}

if (uploaded.upload_status !== "ready") {
  throw new Error(`Upload failed: ${uploaded.upload_status}`);
}

console.log(uploaded.url);
```

```python Python theme={null}
import time

uploaded = client.files.retrieve(file.id)

while uploaded.upload_status in ("pending", "processing"):
    time.sleep(1)
    uploaded = client.files.retrieve(file.id)

if uploaded.upload_status != "ready":
    raise RuntimeError(f"Upload failed: {uploaded.upload_status}")

print(uploaded.url)
```

```ruby Ruby theme={null}
uploaded = client.files.retrieve(id: file.id)

while %w[pending processing].include?(uploaded.upload_status)
  sleep 1
  uploaded = client.files.retrieve(id: file.id)
end

raise "Upload failed: #{uploaded.upload_status}" unless uploaded.upload_status == "ready"

puts uploaded.url
```

```go Go theme={null}
import "time"

uploaded, err := client.Files.Retrieve(context.TODO(), &whopsdk.RetrieveFilesRequest{ID: file.ID})
if err != nil {
  return err
}

for uploaded.UploadStatus == whopsdk.FileUploadStatusPending ||
  uploaded.UploadStatus == whopsdk.FileUploadStatusProcessing {
  time.Sleep(time.Second)
  uploaded, err = client.Files.Retrieve(context.TODO(), &whopsdk.RetrieveFilesRequest{ID: file.ID})
  if err != nil {
    return err
  }
}

if uploaded.UploadStatus != whopsdk.FileUploadStatusReady {
  return fmt.Errorf("upload failed: %s", uploaded.UploadStatus)
}

fmt.Println(*uploaded.URL)
```

```rust Rust theme={null}
let mut uploaded = client.files.retrieve(&file.id, None).await?;

while matches!(
    uploaded.upload_status,
    FileUploadStatus::Pending | FileUploadStatus::Processing
) {
    tokio::time::sleep(std::time::Duration::from_secs(1)).await;
    uploaded = client.files.retrieve(&file.id, None).await?;
}

if !matches!(uploaded.upload_status, FileUploadStatus::Ready) {
    panic!("upload failed: {}", uploaded.upload_status);
}

println!("{}", uploaded.url.unwrap());
```

### Acceder a archivos privados

Las URL de los archivos privados caducan. Para obtener una URL nueva, vuelve a obtener el archivo por su ID:

```typescript TypeScript theme={null}
const file = await client.files.retrieve({ id: "file_xxxxxxxxxxxxx" });
console.log(file.url); // fresh signed URL
```

```python Python theme={null}
file = client.files.retrieve("file_xxxxxxxxxxxxx")
print(file.url)  # fresh signed URL
```

```ruby Ruby theme={null}
file = client.files.retrieve(id: "file_xxxxxxxxxxxxx")
puts file.url # fresh signed URL
```

```go Go theme={null}
file, err := client.Files.Retrieve(context.TODO(), &whopsdk.RetrieveFilesRequest{
  ID: "file_xxxxxxxxxxxxx",
})
fmt.Println(*file.URL) // fresh signed URL
```

```rust Rust theme={null}
let file = client
    .files
    .retrieve(&"file_xxxxxxxxxxxxx".to_string(), None)
    .await?;
println!("{}", file.url.unwrap()); // fresh signed URL
```

## Usar archivos subidos

Cuando el archivo esté en `ready`, pasa su `id` en cualquier llamada a la API que acepte archivos adjuntos:

```typescript TypeScript theme={null}
await client.courses.update({
  id: "course_xxxxxxxxxxxxx",
  thumbnail: { id: file.id },
});
```

```python Python theme={null}
client.courses.update(
    "course_xxxxxxxxxxxxx",
    thumbnail={"id": file.id},
)
```

```ruby Ruby theme={null}
client.courses.update(
  id: "course_xxxxxxxxxxxxx",
  thumbnail: { id: file.id },
)
```

```go Go theme={null}
client.Courses.Update(context.TODO(), &whopsdk.UpdateCoursesRequest{
  ID:        "course_xxxxxxxxxxxxx",
  Thumbnail: &whopsdk.UpdateCoursesRequestThumbnail{ID: file.ID},
})
```

```rust Rust theme={null}
client
    .courses
    .update(
        &"course_xxxxxxxxxxxxx".to_string(),
        &UpdateCoursesRequest {
            thumbnail: Some(UpdateCoursesRequestThumbnail { id: file.id }),
            ..Default::default()
        },
        None,
    )
    .await?;
```

## Propiedades del archivo

| Propiedad | Descripción |
| - | - |
| `id` | Identificador único (p. ej., `file_xxxxxxxxxxxxx`) |
| `filename` | Nombre de archivo original |
| `content_type` | Tipo de medio (p. ej., `image/jpeg`), deducido de la extensión del nombre del archivo |
| `size` | Tamaño del archivo en bytes. `null` hasta que termina la subida |
| `url` | Dónde descargar el archivo: una URL de red de distribución de contenido permanente si es público, una URL firmada que caduca si es privado. `null` hasta que termina la subida |
| `upload_status` | Estado: `pending`, `processing`, `ready` o `failed` |
| `visibility` | `public` o `private` |
| `upload_url` | Una URL prefirmada a la que hacer `PUT` de los bytes. Solo presente en la respuesta de `create` |
| `upload_headers` | Encabezados que enviar con el `PUT` de subida. Solo presentes en la respuesta de `create` |


## Related topics

- [Subir archivos directamente](https://docs.whop.com/es/developer/guides/direct-file-uploads.md)
- [Reembolsos y disputas](https://docs.whop.com/es/developer/guides/refunds-and-disputes.md)
- [API de chat](https://docs.whop.com/es/developer/guides/chat.md)
