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

# Crear un token de subida para subidas desde el navegador

> Crea un token de subida de corta duración que fija ruta o carpeta, tamaño, extensiones y visibilidad. Úsalo en navegadores en vez de tu clave de API.

Crea un token de subida que un navegador u otro cliente no confiable puede usar para subir archivos, sin tu clave de API.
El token fija cada restricción que envías: un `path` para un archivo o un `prefix` para cualquier archivo de una carpeta,
el tamaño máximo, las extensiones permitidas y la visibilidad. Solo funciona en las rutas de subida, y deja de funcionar
cuando se revoca la clave de API que lo creó. El token se muestra una sola vez.

**Ámbito:** `blob:write`.

**path** `string`

Ruta exacta a la que puede subir el token. Usa este o `prefix`, no ambos.

**prefix** `string`

Carpeta en la que puede subir el token. El sufijo aleatorio es obligatorio. Usa este o `path`, no ambos.

**visibility** `string`

`public` o `private`. Lo fija el token.

**max\_size** `number`

Archivo más grande que acepta el token, en bytes.

**allowed\_extensions** `string[]`

De 1 a 20 extensiones, en minúsculas, sin el punto.

**cache\_control** `string`

`cache_control` fijo para los objetos subidos.

**content\_disposition** `string`

`inline` o `attachment` fijo para los objetos subidos.

**expires\_at** `string`

Marca de tiempo ISO 8601 para la eliminación de los objetos subidos.

**metadata** `object`

`metadata` fija para los objetos subidos. Enterprise-12 o superior.

**overwrite** `boolean`

Permite que las subidas con este token reemplacen un archivo existente. Por defecto `false`: sin él, el token nunca
sobrescribe un archivo que ya existe.

**expires\_in** `number`

Segundos que el token sigue válido, de 60 a 3600. Por defecto `900`.

**max\_uses** `number`

Cuántas subidas permite el token, de 1 a 100. Por defecto `1`.

**workspace\_id** `string`

El ID del workspace, cuando el blob pertenece a un workspace. La petición actúa sobre el blob del propietario del
workspace y necesita el permiso `blob:read` del workspace (`blob:manage` en las rutas que modifican datos). Omítelo
para actuar sobre tu propio blob.

### Ejemplo de petición

```bash theme={null}
curl -X POST "https://blob.vertracloud.app/v1/upload-tokens" \
  -H "Authorization: Bearer $VERTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prefix":"avatars/","max_size":5000000,"allowed_extensions":["png","jpg","webp"],"expires_in":900}'
```

### Respuesta

**response** `object`

El token. Se muestra una vez.

**propiedades**

**token** `string`

Token de subida, que empieza por `vcup_`. Se muestra una vez; guárdalo solo donde se hace la subida.

**expires\_at** `string`

Cuándo deja de funcionar el token, como marca de tiempo ISO 8601.

**max\_uses** `number`

Cuántas subidas permite el token.

```json Response theme={null}
{
  "response": {
    "token": "vcup_9f2c7d1e4b8a6035c2f1d9e7a4b3c8d2",
    "expires_at": "2026-10-14T12:15:00.000Z",
    "max_uses": 1
  }
}
```

### Respuestas de error

**code** `string`

El código de error que indica el motivo del fallo. Valores posibles:

* `AUTH_TOKEN_MISSING` (`401`): No se envió la cabecera `Authorization`.
* `API_KEY_INVALID` (`401`): La clave de API no existe, fue revocada o su secreto no coincide.
* `API_KEY_SCOPE_DENIED` (`403`): La clave no tiene el ámbito que necesita esta ruta (`blob:read` o `blob:write`); `details.required` lo indica.
* `WORKSPACE_PERMISSION_DENIED` (`403`): Solo con `workspace_id`: no eres miembro, o tu rol no tiene el permiso de blob.
* `WORKSPACE_NOT_FOUND` (`404`): Solo con `workspace_id`: no existe un workspace con ese ID, o no eres miembro.
* `BLOB_NAMESPACE_SUSPENDED` (`403`): El almacenamiento de blob de la cuenta está suspendido, o su plan expiró. Las subidas y otras escrituras se rechazan desde el inicio del periodo de gracia de 72 horas.
* `VALIDATION_ERROR` (`400`): Un parámetro o un campo del cuerpo no superó la validación. `details.path` indica el campo.
* `PLAN_RESTRICTED_FEATURE` (`403`): Se envió `metadata` en un plan inferior a Enterprise-12.
* `RATE_LIMIT_EXCEEDED` (`429`): Más de 60 tokens creados en un minuto; `details.retry_after` indica cuántos segundos esperar.

```json Error Response (401) theme={null}
{
  "code": "AUTH_TOKEN_MISSING"
}
```

```json Error Response (403) theme={null}
{
  "code": "API_KEY_SCOPE_DENIED"
}
```

```json Error Response (404) theme={null}
{
  "code": "WORKSPACE_NOT_FOUND"
}
```

```json Error Response (400) theme={null}
{
  "code": "VALIDATION_ERROR"
}
```


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