API de Should I Bid
El mismo análisis que la app, controlado desde tus scripts y tus automatizaciones: ideas de palabras clave, estimación de coste, lanzamiento y resultados, con las mismas reglas de créditos y las mismas salvaguardas.
API REST · JSON · OpenAPI 3.1 · incluida en todos los planes de pago
Empezar
Una clave, una cabecera, una petición.
En Should I Bid › Integraciones › Crear clave. Marca «Permitir lanzar análisis» si tu script debe lanzar análisis. La clave solo se muestra una vez; de ella únicamente se guarda la huella.
Cada petición lleva la cabecera Authorization: Bearer sib_live_… Se rechaza una clave puesta en la URL: acabaría en los registros.
GET /api/v1/account devuelve tu saldo, tu plan, tus empresas y los identificadores de sus productos.
curl -H "Authorization: Bearer $SIB_API_KEY" https://shouldibid.app/api/v1/accountRecorrido tipo
El recorrido completo de Vision: generar ideas para un producto, estimar su coste, lanzarlas y leer los resultados.
Hasta 3 fuentes: productos de la empresa o páginas web. La respuesta incluye las ideas nuevas, las ya analizadas con su puntuación y un suggestion_batch_id válido durante 24 horas para un único lanzamiento.
POST /api/v1/suggestions
{"sources":[{"product_id":"…"}]}No se lanza nada: lista depurada, créditos que se reservarán, saldo disponible, límite del día y posibles bloqueos.
POST /api/v1/analyses/estimate
{"suggestion_batch_id":"…"}max_credits es obligatorio: es el importe máximo que aceptas. En un lote de Vision, solo se descuentan las palabras clave recomendadas (puntuación de 50 o más). Respuesta 201 con el identificador del análisis.
POST /api/v1/analyses
{"suggestion_batch_id":"…","max_credits":20}Un análisis tarda de 3 a 10 minutos: consúltalo cada 30 a 60 segundos hasta que termine y lee después los veredictos Pujar, Probar o Descartar, ordenados por puntuación.
GET /api/v1/analyses/{analysis_id}Referencia
URL base: https://shouldibid.app/api/v1. Respuestas en JSON, nunca almacenadas en caché, con una cabecera X-Request-Id que debes indicar al soporte.
| Método | Ruta | Función |
|---|---|---|
| GET | /api/v1/account | Cuenta: plan, créditos disponibles, límite del día, empresas y productos. |
| GET | /api/v1/analyses | Historial de análisis, con filtros (estado, empresa, nombre) y paginación. |
| POST | /api/v1/analyses | Lanza un análisis (consume créditos); max_credits obligatorio. |
| POST | /api/v1/analyses/estimate | Estimación de coste sin lanzar nada: créditos que se reservarán, saldo, límite, bloqueos. |
| GET | /api/v1/analyses/{analysis_id} | Progreso y resultados de un análisis, con las palabras clave ordenadas por puntuación. |
| POST | /api/v1/analyses/{analysis_id}/cancel | Detiene un análisis en curso; las palabras clave sin analizar no se descuentan. |
| GET | /api/v1/analyses/{analysis_id}/keywords/{keyword_id} | Detalle de una palabra clave: puntuación, decisión, subpuntuaciones, justificación, anunciantes. |
| POST | /api/v1/suggestions | Ideas de palabras clave de Vision a partir de 1 a 3 fuentes (gratis). |
| POST | /api/v1/companies | Crea la ficha de una cuenta de empresa que aún no tiene ninguna, o un nuevo cliente de agencia (se rechazan los duplicados). |
| GET | /api/v1/companies/{company_id} | Ficha de empresa completa (textos, competidores, productos con todos sus campos) y reglas de modificación de la cuenta. |
| POST | /api/v1/companies/{company_id} | Modifica solo los campos enviados (null = vaciar); no se sobrescribe nada más. |
| POST | /api/v1/companies/{company_id}/delete | Elimina un cliente de agencia que no tiene ningún análisis. La ficha de una cuenta de empresa no se puede eliminar. |
| POST | /api/v1/companies/{company_id}/products | Añade un producto a una ficha (20 como máximo, se rechaza un nombre repetido). |
| POST | /api/v1/companies/{company_id}/products/{product_id} | Modifica solo los campos enviados del producto. |
| POST | /api/v1/companies/{company_id}/products/{product_id}/delete | Elimina un producto (se rechaza mientras haya un análisis en curso que lo use); los análisis terminados conservan sus resultados. |
| GET | /api/v1/companies/{company_id}/advertisers | Competidores: anunciantes vistos en las palabras clave analizadas de una ficha (cuota, primer anuncio, posición). |
| GET | /api/v1/companies/{company_id}/competitor-gap | Competidores: diferencia con los competidores declarados (solo ellos, tú y ellos, solo tú). |
| GET | /api/v1/companies/{company_id}/brand-watch | Competidores: quién puja por las búsquedas de tu marca, con los anuncios que la citan en primer lugar. |
| GET | /api/v1/analyses/{analysis_id}/advertisers | Competidores de un análisis: cuota de voz en sus palabras clave, con su decisión pujar / probar / descartar. |
| GET | /api/v1/advertisers | Encuentra el dominio de un anunciante a partir de sus primeras letras. |
| GET | /api/v1/advertisers/{domain} | Ficha de un anunciante: sus búsquedas, posiciones y último anuncio, página por página. |
| GET | /api/v1/advertisers/{domain}/history | Historial de los anuncios de un anunciante en una búsqueda. |
| GET | /api/v1/openapi.json | Esta referencia en formato OpenAPI 3.1 (pública, sin clave). |
Salvaguardas
Pensadas para que un script nunca pueda gastar más de lo previsto.
Solo lectura por defecto; lanzar análisis y modificar fichas son dos casillas que marcas expresamente en la clave. Máximo 10 claves activas, con revocación inmediata.
Máximo 200 créditos cada 24 horas para el conjunto de los lanzamientos hechos fuera de la app, ajustable en Integraciones (0 = ningún lanzamiento).
Hasta 5 análisis lanzados por la API o por Claude pueden ejecutarse a la vez; se libera un hueco en cuanto todas las palabras clave de un análisis tienen su resultado. Si se supera, el lanzamiento recibe un error 409 que lista los análisis en curso.
Por encima de ese número, se rechaza la petición con la lista de las palabras clave sobrantes: no se recorta nada en silencio.
300 peticiones por minuto en total, de ellas 120 lecturas y 10 escrituras por minuto; sugerencias: 5 por minuto y 30 al día, por cuenta. Cada respuesta indica la regla y lo que queda en las cabeceras RateLimit-Policy y RateLimit; un rechazo 429 indica el tiempo de espera en Retry-After.
Una clave solo ve los análisis y las empresas de su cuenta; «no existe» y «no es tuyo» devuelven el mismo error 404.
Errores
Cada error lleva un código fijo, un mensaje en inglés y el identificador de la petición.
Formato
{ "error": { "code": "…", "message": "…", "details": { }, "request_id": "…" } }| Código | HTTP | Significado |
|---|---|---|
unauthorized | 401 | Clave ausente, no válida o revocada. |
forbidden | 403 | Cuenta sin plan de pago (details.reason = plan_required, con el enlace a los planes) o acceso aún no abierto. |
insufficient_scope | 403 | Clave de solo lectura para una acción de lanzamiento, o sin el permiso «Modificar fichas» para escribir en una ficha. |
api_disabled | 503 | API cerrada temporalmente. |
not_found | 404 | Recurso inexistente o de otra cuenta. |
method_not_allowed | 405 | Método no permitido (consulta la cabecera Allow). |
invalid_request | 422 | Parámetros no válidos (detalle en details.issues). |
payload_too_large | 413 | Cuerpo de la petición superior a 256 KB. |
rate_limited | 429 | Demasiadas peticiones (consulta la cabecera Retry-After). |
insufficient_credits | 402 | Saldo de créditos insuficiente. |
daily_cap_reached | 429 | Límite diario alcanzado. |
concurrency_limit_reached | 409 | Límite de análisis en paralelo alcanzado (details.active_analyses lista los que están en curso). |
too_many_keywords | 422 | Más de 200 palabras clave en el lanzamiento. |
max_credits_exceeded | 422 | El coste supera max_credits. |
company_required | 422 | Hay varias empresas: indica company_id. |
suggestion_batch_invalid | 422 | Lote de sugerencias desconocido, caducado o ya utilizado. |
conflict | 409 | Conflicto con el estado de la ficha (details.reason): ficha ya creada, cliente o producto duplicado, cliente con análisis, producto con un análisis en curso, modificación simultánea. |
limit_reached | 422 | Límite alcanzado: 20 productos por ficha como máximo. |
unavailable | 503 | Servicio no disponible de forma temporal: vuelve a intentarlo. |
internal | 500 | Error inesperado: comunica el request_id al soporte. |
Versiones
La versión va en la URL (/api/v1): lo que funciona hoy seguirá funcionando.
En la v1 solo se añade (rutas nuevas, parámetros opcionales nuevos, campos nuevos en las respuestas); no se elimina ni se renombra nada. Tu código debe ignorar los campos que no conoce.
Un cambio que rompería un script existente llega en una versión nueva (/api/v2). La v1 sigue en servicio al menos 6 meses después de anunciar la nueva versión.
Antes de retirar nada, la ruta o el campo se marca como deprecated en la especificación OpenAPI, sus respuestas llevan las cabeceras Deprecation y Sunset con las fechas, y el cambio se anuncia en esta página.
Descripción completa, legible por máquinas: impórtala en Postman, Insomnia o un generador de clientes.
Incluida en todos los planes de pago · 1 crédito = 1 palabra clave analizada