Documentación de API

POST /analyze/project (recomendado)

Úsalo cuando quieras los prompts guardados del proyecto en SEOforGPT. Cuerpo: solo projectId. Devuelve 202 mientras se ejecutan jobs multiproveedor, o 200 cuando el informe ya está completo.

curl --request POST \
  --url https://www.seoforgpt.io/api/v1/analyze/project \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"projectId":"<uuid>"}'

POST /analyze/custom

Úsalo para conjuntos de prompts ad hoc o una marca distinta de la guardada en la app. Cuerpo: projectId, brand, prompts (strings u objetos { prompt }), más competitors opcional. Máximo 20 prompts. Devuelve HTTP 200 con un id de informe de tipo visibility_analysis_api.

curl --request POST \
  --url https://www.seoforgpt.io/api/v1/analyze/custom \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"projectId":"<uuid>","brand":"YourBrand","prompts":["query 1","query 2"]}'

POST /analyze

Dispatcher heredado. Sigue soportado, pero las nuevas integraciones deberían preferir las rutas explícitas anteriores. Acepta testId, projectId + brand + prompts, projectId + brand + crawlRecordId, o solo projectId.

GET /reports/latest

Úsalo cuando no quieras controlar tú mismo un id de informe. Parámetros de query: projectId obligatorio, source=main|custom opcional, view=raw|summary|full opcional y answer_detail=summary|full opcional para informes completos.

curl --request GET \
  --url "https://www.seoforgpt.io/api/v1/reports/latest?projectId=<uuid>&source=main&view=full&answer_detail=summary" \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN"

GET /reports/:id

Recupera un id de informe específico. El data.type devuelto es visibility_analysis, visibility_analysis_api o generated_content. Los informes de visibilidad aceptan los mismos parámetros view y answer_detail.

curl --request GET \
  --url "https://www.seoforgpt.io/api/v1/reports/REPORT_ID_FROM_PREVIOUS_STEP?view=full&answer_detail=summary" \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN"

Después de 202 desde /analyze/project, consulta esta ruta hasta que data.status sea terminal.

GET /reports/:id/provider-answer

Usa esta ruta de profundización para recuperar una respuesta bruta de proveedor y citas después de leer un informe full seguro para agentes con answer_detail=summary.

curl --request GET \
  --url "https://www.seoforgpt.io/api/v1/reports/REPORT_ID/provider-answer?promptKey=<prompt>&provider=openai" \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN"

POST /generate-content

Cuerpo: projectId, platform (blog, linkedin, thread), topic, más metadata y promptType opcionales. Para briefs de actualización, incluye metadata.content_action=optimize_existing_url con target_url y target_title de content-suggestions.

curl --request POST \
  --url https://www.seoforgpt.io/api/v1/generate-content \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"projectId":"<uuid>","platform":"blog","topic":"How to measure AI search visibility"}'

• La respuesta incluye data.id para GET /reports/:id y puede incluir data.status: processing para blogs.
• También devuelve context_quality y context_message para saber si el borrador usó análisis de sitio completado.

POST /readiness

Ejecuta el mismo flujo de preparación del sitio que la app. Cuerpo: projectId obligatorio, forceRerun opcional y sustitución url opcional. La respuesta incluye data.id, data.cached y data.result.

curl --request POST \
  --url https://www.seoforgpt.io/api/v1/readiness \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"projectId":"<uuid>","forceRerun":false}'

POST /suggest-prompts

Genera sugerencias de prompts desde un crawl existente. Cuerpo: crawlRecordId obligatorio, projectId opcional, brand opcional y competitors opcional. La respuesta incluye prompt_count y puede incluir un id de test guardado en report_url.

curl --request POST \
  --url https://www.seoforgpt.io/api/v1/suggest-prompts \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"crawlRecordId":"<uuid>","projectId":"<uuid>"}'

POST /projects/:id/content-suggestions

Genera oportunidades enrutadas usando el mismo planificador de contenido de la app. Los temas incluyen content_action, target_url, target_title, coverage_status, match_reason y persisted. Los artículos nuevos y briefs de actualización se devuelven en topics; los items covered_existing_url son señales para saltar devueltas en skipped_topics con persisted=false.

curl --request POST \
  --url https://www.seoforgpt.io/api/v1/projects/<project_id>/content-suggestions \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"count":10}'

POST /keys

Crea una clave de API. Cuerpo: name opcional y expires_at opcional. Devuelve HTTP 201 con data.key.

curl --request POST \
  --url https://www.seoforgpt.io/api/v1/keys \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"name":"CI automation","expires_at":"2027-06-01T00:00:00.000Z"}'

GET /keys

Lista tus claves de API con prefijo, nombre, fecha de creación, último uso y caducidad.

DELETE /keys/:id

Elimina una clave de API propiedad del usuario autenticado.