# Descripción general de la API

Autenticación, endpoint, errores y límites de velocidad.

## Descripción general de la API

Un único endpoint JSON-RPC autenticado con tokens de API. Llama a cualquier método por nombre.

> ℹ️ **¿No necesitas código?**
> <p>
>     Las <a href="/es/guides/overview">Guías</a> configuran Formstep en Zapier clic a clic, sin que tengas que llamar a la API tú mismo.
>   </p>

<h2 id="endpoint">Endpoint</h2>
<p>
  Todas las solicitudes van a una única URL mediante <code>POST</code>. Pasa el nombre del método y los parámetros en JSON.
</p>

```
POST https://api.formstep.io/api/v1
```

<h2 id="auth">Autenticación</h2>
<p>
  Pasa tu token de API como bearer token en el encabezado <code>Authorization</code>. Los tokens están vinculados a un espacio de trabajo —
  créalos desde <strong>OAuth y claves de API</strong> en la barra lateral.
</p>

  
    
```
curl -X POST https://api.formstep.io/api/v1 \
  -H "Authorization: Bearer fb_..." \
  -H "Content-Type: application/json" \
  -d '{"method": "forms.list", "params": {}}'
```

  
  
    
```
const res = await fetch('https://api.formstep.io/api/v1', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FORMSTEP_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ method: 'forms.list', params: {} }),
})
const data = await res.json()
```

  
  
    
```
import os, requests
res = requests.post(
    "https://api.formstep.io/api/v1",
    headers={"Authorization": f"Bearer {os.environ['FORMSTEP_TOKEN']}"},
    json={"method": "forms.list", "params": {}},
)
data = res.json()
```

  

> ⚠️ **Mantén los tokens en el servidor**
> <p>Nunca incluyas tokens en código del navegador. Usa un proxy de backend para llamadas del lado del cliente.</p>

<h2 id="request-format">Formato de solicitud</h2>
<p>Cada solicitud es un objeto JSON con dos campos:</p>

```
{
  "method": "forms.list",
  "params": {
    "workspaceId": "abc123..."
  }
}
```

<h2 id="response-format">Formato de respuesta</h2>
<p>
  Cada respuesta es un objeto JSON con un campo <code>ok</code>. En caso de éxito:
</p>

```
{
  "ok": true,
  "data": { ... }
}
```

<h2 id="errors">Errores</h2>
<p>
  En caso de fallo, <code>ok</code> es <code>false</code> y un objeto <code>error</code> contiene un código legible por máquina y un mensaje
  legible por humanos:
</p>

```
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'name' is required."
  }
}
```

<p>Códigos de error comunes:</p>
<ul>
  <li>
    <code>VALIDATION_ERROR</code> (400) — parámetros inválidos o faltantes
  </li>
  <li>
    <code>UNAUTHORIZED</code> (401) — token de API ausente o inválido
  </li>
  <li>
    <code>UPGRADE_REQUIRED</code> (402) — la funcionalidad requiere un nivel de suscripción superior
  </li>
  <li>
    <code>FORBIDDEN</code> (403) — el token no tiene acceso al recurso
  </li>
  <li>
    <code>CONFLICT</code> (409) — conflicto de estado del recurso, como un nombre duplicado
  </li>
  <li>
    <code>NOT_FOUND</code> (404) — el recurso no existe
  </li>
  <li>
    <code>METHOD_NOT_FOUND</code> (404) — nombre de método desconocido
  </li>
  <li>
    <code>RATE_LIMITED</code> (429) — demasiadas solicitudes
  </li>
  <li>
    <code>INTERNAL_ERROR</code> (500) — error inesperado del servidor
  </li>
</ul>

<h2 id="rate-limits">Límites de velocidad</h2>
<p>
  Las solicitudes a la API están limitadas a <strong>120 solicitudes por minuto</strong> por token. Superar el límite devuelve{' '}
  <code>429 Too Many Requests</code>.
</p>

<h2 id="next-steps">Próximos pasos</h2>
<div class="not-prose grid gap-3 sm:grid-cols-2">
  - [Métodos de la API](/es/developers/rest-api) — Lista completa de métodos disponibles
  - [Tokens de API](/es/developers/api-tokens) — Crea y gestiona tokens
  - [Referencia de webhooks](/es/developers/webhooks-reference) — Esquema de payload y firma
  - [Servidor MCP](/es/developers/mcp-server) — Usa Formstep desde agentes de IA
</div>