Uso automatizado

Antes, abrir una cuenta de Hushscript necesitaba una persona, al menos una vez. Eso ya no es toda la historia. Un flujo que empieza por el pago le permite a un agente abrir su propia cuenta, financiarla y usarla, sin ningún titular humano en ningún punto del proceso. /developers y /mcp documentan las dos interfaces que esa cuenta usa después; esta página es la guía para conseguir una.

Regístrate

POST /v1/agent/accounts abre un registro sin interfaz. Todavía no hay cuenta, ni cookie, ni token: solo una compra pendiente.

curl -X POST https://api.hushscript.com/v1/agent/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "contact_email": "ops@example-agent.dev",
    "pack_id": "300min",
    "accept_terms_version": "2026-08-01",
    "agent": {
      "name": "research-crawler",
      "platform": "langgraph",
      "contact_url": "https://example-agent.dev/bots/research-crawler"
    }
  }'

{
  "signup_id": "hsr1:eu:4c3a1f9e7b2d4e6f8a0c1b2d3e4f5061",
  "claim_secret": "cs_9f3d2a1b7e6c4f5a8b9d0e1f2a3b4c5d",
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_a1B2c3D4e5F6",
  "pack": "300min",
  "amount": 599,
  "currency": "usd",
  "expires_at": 1789112400
}

contact_email sirve solo para recibos y avisos, nunca para iniciar sesión. pack_id es uno de 45min, 300min, 900min, 1800min, 6000min; nunca envíes tú mismo amount ni currency, ambos se derivan del paquete en el servidor. Solo los dos paquetes más pequeños, 45min y 300min, se pueden comprar al registrarse. Un pack_id mayor se rechaza, y el rechazo trae details.allowed_packs, que enumera lo que esta cuenta puede comprar ahora mismo, para que quien llama pueda reintentar sin adivinar. El resto de la escalera se desbloquea con la antigüedad, no con el volumen: consulta Qué puede comprar una cuenta nueva más abajo. accept_terms_version debe coincidir exactamente con la versión de política vigente en el servidor, o la llamada falla con policy_version_stale, que indica el valor actual en su cuerpo. Una sugerencia opcional data_region solo se respeta cuando coincide con la región que ya implica tu ubicación de red. Un dry_run: true opcional valida todo sin crear una sesión de Stripe ni realizar ningún cargo; su signup_id lleva el prefijo dry_ y nunca se puede reclamar.

claim_secret se muestra exactamente una vez, en esta respuesta. Hushscript solo almacena su hash. Perderlo antes de la llamada de reclamo significa perder el registro: no existe ninguna ruta de recuperación para un secreto de reclamo, y el pago retenido en garantía se reembolsa mediante el barrido descrito más abajo, no se devuelve mediante una búsqueda.

Completa el pago en tu propio navegador

checkout_url es una página de Stripe Checkout alojada. Es el único paso de todo este flujo que necesita un navegador, y no tiene que ser el navegador de una persona: un agente puede manejarlo con su propia automatización (llenar los campos de la tarjeta, enviar, seguir la redirección). Hushscript nunca ve los datos de la tarjeta en ningún caso; Stripe sí. La ventana para completarlo y luego reclamar es de 30 minutos, el expires_at de arriba.

Un registro que se paga pero nunca se reclama se reembolsa automáticamente mediante un barrido cada hora, aproximadamente una hora después de que se cierra esa ventana de 30 minutos. El reembolso es completo, porque los minutos solo se acreditan a un saldo en el momento del reclamo, así que un registro sin reclamar nunca tuvo ninguno que consumir.

Reclama la cuenta

POST /v1/agent/accounts/{signup_id}/claim convierte un registro pagado y sin reclamar en una cuenta real, en una sola llamada.

curl -X POST https://api.hushscript.com/v1/agent/accounts/hsr1:eu:4c3a1f9e7b2d4e6f8a0c1b2d3e4f5061/claim \
  -H "Content-Type: application/json" \
  -d '{"claim_secret": "cs_9f3d2a1b7e6c4f5a8b9d0e1f2a3b4c5d"}'

{
  "user_id": "usr_7d1a2b3c4d5e6f708192a3b4c5d6e7f8",
  "pat": "hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170",
  "scopes": [
    "transcripts:read",
    "transcripts:write",
    "transcribe",
    "account:read",
    "export",
    "billing",
    "pat:rotate"
  ],
  "balance_seconds": 18000
}

Reclamar es de un solo uso. Crea exactamente una cuenta, con una identidad de inicio de sesión sintética e irresoluble detrás, concede el paquete pagado exactamente una vez aunque se reintente la solicitud, y emite exactamente un PAT: el valor pat de arriba, también mostrado exactamente una vez.

Un secreto incorrecto, un signup_id desconocido, un registro ya reclamado, uno reembolsado y uno vencido responden todos con el mismo error agent_claim_invalid. A propósito, quien llama no tiene forma de distinguirlos a partir de la respuesta. Solo una vez que el secreto en sí es válido entra en juego el estado del pago: una Checkout Session que todavía no se liquidó responde wrong_state en su lugar.

El balance_seconds de arriba es todo el saldo inicial. Las cuentas de agente no reciben ningún bono de bienvenida ni minutos gratis por verificación de tarjeta como sí recibe la primera cuenta de una persona; parten de nada más que el paquete que pagaron. Eso es deliberado, no un vacío: la cuenta ya estaba pagada antes de existir.

Compra más minutos

Desde aquí la cuenta se comporta como cualquier otra, sobre la misma superficie /v1/ que /developers documenta por completo.

curl -X POST https://api.hushscript.com/v1/billing/purchase \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170" \
  -H "Content-Type: application/json" \
  -d '{
    "pack": "300min",
    "quick_payment_method_id": "pm_1PqR2sT3uV4wX5yZ",
    "idempotency_key": "purchase-2026-09-11-01"
  }'

{
  "balance_seconds": 36000
}

Esto necesita el scope billing, que la respuesta de reclamo de arriba ya concedió, y comparte un límite más estricto de 60 solicitudes por minuto por cuenta con la ruta de guardar tarjeta, antes de la llamada a Stripe que hace cualquiera de las dos.

Qué puede comprar una cuenta nueva

El tamaño de paquete se desbloquea según la antigüedad de los pagos liquidados, no según cuánto gasta una cuenta. Una compra cuenta para el siguiente nivel solo una vez que pasaron 7 días desde su propia fecha de pago, así que una cuenta recién creada no puede alcanzar los paquetes grandes comprando rápido.

Una compra rechazada indica el conjunto actual en details.allowed_packs en lugar de fallar a ciegas. La llamada de registro aplica la primera fila de esa tabla, por eso la guía de arriba compra 300min y no algo más grande. Aparte de la escalera, un tope móvil de consumo de 24 horas limita qué tan rápido se puede gastar el saldo que todavía no superó en antigüedad la ventana de disputa.

Transcribe

Subir y transcribir es el mismo flujo multiparte que en cualquier otra cuenta.

curl -X POST https://api.hushscript.com/v1/uploads \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170" \
  -H "Content-Type: application/json" \
  -d '{
    "size_bytes": 48213504,
    "duration_seconds": 1860,
    "title": "weekly-standup-2026-09-11",
    "idempotency_key": "upload-2026-09-11-01"
  }'

{
  "job_id": "job_3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d",
  "part_urls": [
    { "n": 1, "url": "https://r2.hushscript.com/uploads/job_3a2b1c0d.../part-1?X-Amz-Signature=..." }
  ]
}

Haz PUT de cada parte a su URL prefirmada, luego haz POST a /complete del mismo job con el n y el etag de cada parte enviada de esa forma. Después, consulta el job:

curl https://api.hushscript.com/v1/jobs/job_3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "id": "job_3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d",
  "state": "done",
  "transcript_id": "trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180"
}

curl https://api.hushscript.com/v1/transcripts/trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180 \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "id": "trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180",
  "language": "en",
  "duration_seconds": 1860,
  "body": "..."
}

Rota la credencial

Una cuenta de máquina no tiene contraseña ni un buzón de correo utilizable, así que no existe la ruta de ‘olvidé mi contraseña’ si un PAT se filtra o simplemente hay que reemplazarlo. La rotación es esa ruta.

curl -X POST https://api.hushscript.com/v1/agent/credentials/rotate \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "pat": "hsr1:eu:pat.p9q8r7.1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "pat_id": "p9q8r7",
  "scopes": [
    "transcripts:read",
    "transcripts:write",
    "transcribe",
    "account:read",
    "export",
    "billing",
    "pat:rotate"
  ],
  "expires_at": null
}

La llamada no lleva cuerpo. Emite de forma atómica un sucesor y revoca el token que autenticó la solicitud, así que el PAT anterior falla en la siguientísima llamada hecha con él. El sucesor conserva los scopes, el permiso de facturación, el nombre, la etiqueta de cliente y la política de vencimiento del predecesor. Esta ruta no toca nada más que el propio token de quien llama: no puede listar, emitir ni revocar ninguna otra credencial de la cuenta. Es la única ruta de recuperación de credenciales que tiene una cuenta de máquina, así que rota antes de descartar el token anterior, no después.

Errores

Estos cuatro son específicos de las cuentas de agente y una cuenta humana nunca los alcanza:

Una vez que el secreto de reclamo en sí es válido, una Checkout Session sin pagar responde wrong_state (4001) en lugar de agent_claim_invalid. El catálogo completo está en el documento OpenAPI.

Límites

Las llamadas están limitadas a 1,200 por minuto. Para una cuenta de agente, ese presupuesto pertenece a la cuenta, no al token individual: cada credencial del linaje de rotación consume del mismo cupo, así que rotar un PAT no le da al sucesor una asignación nueva. Las dos escrituras de facturación, guardar una tarjeta y comprar un paquete, comparten un límite más estricto de 60 por minuto por cuenta, antes de la llamada a Stripe que hace cualquiera de las dos. El tope de compra de 24 horas de arriba se cuenta de la misma forma, por cuenta en lugar de por credencial.

Más información

Esta página cubre el ciclo de vida de la cuenta: abrirla, financiarla y mantener viva su credencial. Para todo lo que la cuenta puede hacer después, consulta la API REST, incluido el documento OpenAPI completo, o el servidor MCP para la misma cuenta mediante herramientas en lugar de HTTP puro.