Análisis guardados

Cada llamada a POST /v1/analyze o POST /v1/classify crea un análisis con id an_…. Si no pediste keep_results: false, sus resultados quedan guardados y puedes consultarlos con estos endpoints.

Guardar resultados no implica guardar el fichero: eso lo decide storage. Ver Almacenamiento y privacidad.

Recuperar un análisisCopy Anchor Link

GET /v1/analyses/{id}

Devuelve el objeto analysis (o classification) con su estado actual y las URLs firmadas vigentes en exports. Funciona con claves de cualquier modo, siempre que el análisis sea de tu cuenta.

Devuelve 404 resource_missing si el análisis no existe, es de otra cuenta, lo borraste o se creó con keep_results: false.

Es la forma de consultar un análisis asíncrono si no usas webhooks. Consulta con espera creciente y para cuando status sea completed o failed. Los webhooks son preferibles: no gastan peticiones de tu límite.

curl https://api.constaia.com/v1/analyses/an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2 \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"

Listar análisisCopy Anchor Link

GET /v1/analyses

El listado solo incluye análisis del modo de tu clave (test o live), del más reciente al más antiguo. No incluye los borrados ni los creados con keep_results: false.

{
  "object": "list",
  "data": [
    { "id": "an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2", "object": "analysis", "status": "completed", "…": "…" }
  ],
  "has_more": true,
  "url": "/v1/analyses"
}

PaginaciónCopy Anchor Link

La paginación es por cursor: mientras has_more sea true, pide la página siguiente pasando el id del último elemento como starting_after. No existe un campo next_cursor. Más detalles en Paginación.

#!/usr/bin/env bash
set -euo pipefail

after=""
while :; do
  page=$(curl -sf -G https://api.constaia.com/v1/analyses \
    -H "Authorization: Bearer $CONSTAIA_API_KEY" \
    --data-urlencode "limit=100" \
    --data-urlencode "status=completed" \
    --data-urlencode "metadata[event]=42" \
    ${after:+--data-urlencode "starting_after=$after"})
  echo "$page" | jq -r '.data[] | [.id, .document.type, .verdict.status] | @tsv'
  [ "$(echo "$page" | jq -r .has_more)" = "true" ] || break
  after=$(echo "$page" | jq -r '.data[-1].id')
done

Borrar un análisisCopy Anchor Link

DELETE /v1/analyses/{id}

Borra el fichero (si se guardó), los resultados extraídos y las exportaciones. No se puede deshacer. Después, GET devuelve 404. Los metadatos de facturación (páginas, créditos, tipo) se conservan para tu consumo.

curl -X DELETE https://api.constaia.com/v1/analyses/an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2 \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"

{ "id": "an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2", "object": "analysis", "deleted": true }

En los SDK: await constaia.analyses.delete(id) (JavaScript) y $constaia->analyses->delete($id) (PHP). Si solo quieres que el fichero no se guarde nunca, usa storage: "none" y keep_results: false al analizar; ver Analizar sin guardar nada.

Exportar un análisisCopy Anchor Link

GET /v1/analyses/{id}/export?format=json|csv|xlsx|xml|vcard|pdf

Genera el fichero al momento (por defecto json) y lo devuelve como descarga con Content-Disposition: attachment; filename="an_….xlsx". No caduca como las URLs de exports: puedes pedirlo siempre que el análisis exista. Si el análisis aún no ha terminado, responde 409 analysis_not_completed. Formatos en Exportaciones.

curl -o analisis.xlsx \
  "https://api.constaia.com/v1/analyses/an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2/export?format=xlsx" \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"

Descargas firmadas (/v1/files)Copy Anchor Link

Cuando analizas con export, el campo exports trae URLs como esta:

https://api.constaia.com/v1/files/exp_01J9Z8Q3K4M5N6P7Q8R9S0T1V2?expires=1790157602&sig=…

• No necesitan clave: la firma sig autoriza la descarga. Trátalas como un secreto temporal y no las publiques.
• Caducan a las 24 horas. Después devuelven 404. GET /v1/analyses/{id} solo incluye en exports las que siguen vigentes; si necesitas el fichero más tarde, usa GET /v1/analyses/{id}/export.
• Se sirven siempre desde api.constaia.com, nunca desde una URL del almacenamiento.
• Si modificas expires o sig, la firma deja de ser válida y la respuesta es 404.

Siguientes pasosCopy Anchor Link