# Referencia de la API

> Todos los endpoints de la API de Fileverity con sus parámetros, esquemas de solicitud y de respuesta, códigos de error y ejemplos, generados a partir de la especificación OpenAPI 3.1.

Fuente: https://fileverity.com/es/docs/api-reference

Esta referencia se genera a partir del documento OpenAPI 3.1 de la API, disponible en [https://api.fileverity.com/v1/openapi.json](https://api.fileverity.com/v1/openapi.json), por lo que siempre coincide con la API. Para conceptos y guías, empiece por la [Descripción general](https://fileverity.com/es/docs.md).

## Convenciones

URL base: `https://api.fileverity.com/v1`. Autentique cada solicitud con `Authorization: Bearer <key>`. Los errores comparten un único formato, descrito en [Errores](https://fileverity.com/es/docs/errors.md). Cada respuesta incluye un encabezado `x-request-id`, y las respuestas autenticadas incluyen los encabezados del límite de frecuencia descritos en [Límites de frecuencia y encabezados](https://fileverity.com/es/docs/rate-limits.md). Los objetos anidados se abren en secciones desplegables bajo la tabla.

## Detecciones de texto

### Detectar texto escrito con IA

`POST` `https://api.fileverity.com/v1/text/detections`

Clasifica el texto sin formato como escrito con IA, escrito en parte con IA o escrito por una persona, y devuelve los pasajes escritos con IA. El texto se evalúa y se descarta; no se almacena. La facturación cuenta puntos de código Unicode en unidades de 1000 caracteres, redondeadas hacia arriba en cada solicitud. Las solicitudes rechazadas antes de la evaluación no se cobran. Las claves de prueba devuelven sin cargo un resultado fijo de texto escrito por una persona.

#### Parámetros

| Nombre | Ubicación | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | encabezado | cadena | No | Clave única de hasta 255 caracteres. Repetir la solicitud con la misma clave y el mismo cuerpo en un plazo de 24 horas devuelve la primera respuesta con el encabezado idempotent-replayed: true; la misma clave con un cuerpo distinto devuelve 409. |

#### Cuerpo de la solicitud: application/json, obligatorio

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `model` | cadena | No | ID de modelo o ID de versión fechada. Valor predeterminado: `"fvdoc-3-text"`. |
| `text` | cadena | Sí | Texto sin formato, de al menos 100 palabras y como máximo 100 000 caracteres. |
| `language` | uno de `"en"`, `"fr"`, `"de"`, `"es"`, `"zh"`, `null` | No | Código ISO 639-1. Se detecta automáticamente si se omite. Valor predeterminado: `null`. |

#### Respuestas

| Estado | Descripción | Cuerpo |
| --- | --- | --- |
| 200 | El resultado de la detección. | `TextDetection` |
| 400 | Solicitud no válida. Códigos de error: invalid_json, missing_parameter, text_too_short, unsupported_language, invalid_parameter. | `Error` |
| 401 | Clave de API ausente o no válida. Códigos de error: missing_api_key, invalid_api_key. | `Error` |
| 402 | El saldo o el límite de gasto mensual de la clave no cubre la solicitud. Códigos de error: insufficient_balance, spend_limit_reached. | `Error` |
| 404 | Recurso no encontrado. Códigos de error: model_not_found. | `Error` |
| 409 | Conflicto con el estado actual. Códigos de error: idempotency_mismatch, idempotency_in_progress. | `Error` |
| 413 | Se superó un límite de tamaño. Códigos de error: text_too_long. | `Error` |
| 415 | Tipo de medio o formato de archivo no admitido. Códigos de error: unsupported_media_type. | `Error` |
| 429 | Demasiadas solicitudes. Códigos de error: rate_limited. | `Error` |
| 500 | Error interno; no se cobra. Códigos de error: internal_error. | `Error` |
| 502 | No se pudo completar el análisis; no se cobra. Códigos de error: analysis_failed. | `Error` |
| 503 | No disponible temporalmente u ocupado; no se cobra. Reintente tras el número de segundos que indica el encabezado retry-after. Códigos de error: service_unavailable. | `Error` |

#### Respuesta 200: TextDetection

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | cadena | Sí |  |
| `object` | `"text.detection"` | Sí |  |
| `created` | entero | Sí | Marca de tiempo Unix. |
| `model` | cadena | Sí | Versión fechada que produjo el resultado. |
| `livemode` | booleano | Sí | False con claves de prueba. |
| `language` | uno de `"en"`, `"fr"`, `"de"`, `"es"`, `"zh"` | Sí |  |
| `verdict` | uno de `"ai"`, `"mixed"`, `"human"` | Sí | ai: el texto parece escrito con IA en su totalidad; mixed: pasajes escritos con IA dentro de un texto escrito por una persona; human: no se encontró ningún pasaje escrito con IA. |
| `score` | número | Sí | Puntuación del modelo para el pasaje más parecido a un texto escrito con IA. Mínimo 0. Máximo 1. |
| `ai_fraction` | número | Sí | Proporción del texto evaluado que está dentro de segmentos escritos con IA. Mínimo 0. Máximo 1. |
| `segments` | array de objetos | Sí | Pasajes escritos con IA, como posiciones en el texto enviado medidas en puntos de código Unicode. Los límites son aproximados y pueden incluir oraciones adyacentes. |
| `usage` | objeto | Sí |  |

**segments: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `start` | entero | Sí |  |
| `end` | entero | Sí | Exclusivo. |
| `score` | número | Sí | Mínimo 0. Máximo 1. |

**usage: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `characters` | entero | Sí | Puntos de código Unicode evaluados. |
| `free_characters` | entero | Sí | Caracteres cubiertos por su asignación de inicio gratuito; no se facturan. |
| `billed_units` | entero | Sí | Unidades de 1000 caracteres realmente cobradas, una vez descontados los caracteres gratuitos; billed_units × precio unitario es el coste. |

#### Códigos de error

| Código | Estado |
| --- | --- |
| `invalid_json` | 400 |
| `missing_parameter` | 400 |
| `unsupported_media_type` | 415 |
| `text_too_short` | 400 |
| `text_too_long` | 413 |
| `unsupported_language` | 400 |
| `model_not_found` | 404 |
| `insufficient_balance` | 402 |
| `spend_limit_reached` | 402 |
| `service_unavailable` | 503 |
| `analysis_failed` | 502 |
| `invalid_parameter` | 400 |
| `idempotency_mismatch` | 409 |
| `idempotency_in_progress` | 409 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Ejemplo

**Solicitud: cURL**

```bash
curl https://api.fileverity.com/v1/text/detections \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -Rs '{text: .}' essay.txt)"
```

**Respuesta**

```json
{
  "id": "tdet_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "text.detection",
  "created": 1793664000,
  "model": "fvdoc-3-text-2026-11-03",
  "livemode": true,
  "language": "en",
  "verdict": "mixed",
  "score": 0.97,
  "ai_fraction": 0.41,
  "segments": [
    {
      "start": 212,
      "end": 433,
      "score": 0.97
    },
    {
      "start": 579,
      "end": 790,
      "score": 0.93
    }
  ],
  "usage": {
    "characters": 1412,
    "free_characters": 0,
    "billed_units": 2
  }
}
```

## Archivos

### Subir un archivo

`POST` `https://api.fileverity.com/v1/files`

Sube un archivo para analizarlo. Envíe los archivos de hasta 4 MB como multipart/form-data en el campo file; la respuesta tiene el estado uploaded. Los archivos de más de 4 MB deben subirse con una URL prefirmada. Envíe JSON con filename, content_type y bytes (documentos de hasta 50 MB); la respuesta tiene el estado pending y un objeto upload con una URL prefirmada: envíe a ella los bytes del archivo con PUT y los encabezados indicados antes de que caduque. Un archivo se elimina cuando se inicia un análisis y, como máximo, a las 24 horas. Un espacio de trabajo puede contener a la vez hasta 50 archivos sin caducar y 200 MB por modo.

#### Parámetros

| Nombre | Ubicación | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | encabezado | cadena | No | Clave única de hasta 255 caracteres. Repetir la solicitud con la misma clave y el mismo cuerpo en un plazo de 24 horas devuelve la primera respuesta con el encabezado idempotent-replayed: true; la misma clave con un cuerpo distinto devuelve 409. |

#### Cuerpo de la solicitud: multipart/form-data, obligatorio

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `file` | cadena | Sí | Formato binary. |

#### Cuerpo de la solicitud: application/json, obligatorio

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `filename` | cadena | No |  |
| `content_type` | cadena | Sí | Tipo MIME del archivo, por ejemplo image/jpeg o application/pdf. |
| `bytes` | entero | Sí | Tamaño exacto en bytes. Mínimo 1. Máximo 52 428 800. |

#### Respuestas

| Estado | Descripción | Cuerpo |
| --- | --- | --- |
| 201 | El archivo. | `File` |
| 400 | Solicitud no válida. Códigos de error: invalid_json, missing_parameter, invalid_parameter. | `Error` |
| 401 | Clave de API ausente o no válida. Códigos de error: missing_api_key, invalid_api_key. | `Error` |
| 409 | Conflicto con el estado actual. Códigos de error: idempotency_mismatch, idempotency_in_progress. | `Error` |
| 413 | Se superó un límite de tamaño. Códigos de error: file_too_large. | `Error` |
| 415 | Tipo de medio o formato de archivo no admitido. Códigos de error: unsupported_media_type, unsupported_file. | `Error` |
| 422 | No se puede procesar el archivo. Códigos de error: invalid_file. | `Error` |
| 429 | Demasiadas solicitudes. Códigos de error: pending_files_limit, rate_limited. | `Error` |
| 500 | Error interno; no se cobra. Códigos de error: internal_error. | `Error` |

#### Respuesta 201: File

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | cadena | Sí |  |
| `object` | `"file"` | Sí |  |
| `filename` | cadena o null | Sí |  |
| `bytes` | entero o null | Sí |  |
| `content_type` | cadena | Sí |  |
| `status` | uno de `"pending"`, `"uploaded"` | Sí | pending hasta que han llegado los bytes enviados a la URL prefirmada. |
| `livemode` | booleano | Sí | Los archivos solo son visibles para las claves del mismo modo. |
| `created` | entero | Sí | Marca de tiempo Unix. |
| `expires_at` | entero | Sí | Marca de tiempo Unix a partir de la cual se elimina el archivo. |
| `upload` | objeto | No | Presente en la respuesta a una solicitud de subida en JSON. |

**upload: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `url` | cadena | Sí | Las claves de prueba reciben una URL de marcador de posición (test: true); no se sube ni se almacena nada. |
| `method` | `"PUT"` | Sí |  |
| `headers` | objeto de cadenas | Sí |  |
| `expires_at` | entero | Sí | Marca de tiempo Unix. |
| `test` | `true` | No |  |

#### Códigos de error

| Código | Estado |
| --- | --- |
| `invalid_json` | 400 |
| `missing_parameter` | 400 |
| `unsupported_media_type` | 415 |
| `unsupported_file` | 415 |
| `invalid_file` | 422 |
| `file_too_large` | 413 |
| `pending_files_limit` | 429 |
| `invalid_parameter` | 400 |
| `idempotency_mismatch` | 409 |
| `idempotency_in_progress` | 409 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Ejemplo

**Solicitud: cURL**

```bash
curl https://api.fileverity.com/v1/files \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -F file=@claim-photo.jpg
```

**Respuesta**

```json
{
  "id": "file_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "file",
  "filename": "claim-photo.jpg",
  "bytes": 2481920,
  "content_type": "image/jpeg",
  "status": "uploaded",
  "livemode": true,
  "created": 1793700000,
  "expires_at": 1793786400
}
```

### Recuperar un archivo

`GET` `https://api.fileverity.com/v1/files/{id}`

Devuelve el archivo y si sus bytes han llegado.

#### Parámetros

| Nombre | Ubicación | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- | --- |
| `id` | ruta | cadena | Sí | ID del archivo. |

#### Respuestas

| Estado | Descripción | Cuerpo |
| --- | --- | --- |
| 200 | El archivo. | `File` |
| 401 | Clave de API ausente o no válida. Códigos de error: missing_api_key, invalid_api_key. | `Error` |
| 404 | Recurso no encontrado. Códigos de error: not_found. | `Error` |
| 429 | Demasiadas solicitudes. Códigos de error: rate_limited. | `Error` |
| 500 | Error interno; no se cobra. Códigos de error: internal_error. | `Error` |

#### Respuesta 200: File

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | cadena | Sí |  |
| `object` | `"file"` | Sí |  |
| `filename` | cadena o null | Sí |  |
| `bytes` | entero o null | Sí |  |
| `content_type` | cadena | Sí |  |
| `status` | uno de `"pending"`, `"uploaded"` | Sí | pending hasta que han llegado los bytes enviados a la URL prefirmada. |
| `livemode` | booleano | Sí | Los archivos solo son visibles para las claves del mismo modo. |
| `created` | entero | Sí | Marca de tiempo Unix. |
| `expires_at` | entero | Sí | Marca de tiempo Unix a partir de la cual se elimina el archivo. |
| `upload` | objeto | No | Presente en la respuesta a una solicitud de subida en JSON. |

**upload: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `url` | cadena | Sí | Las claves de prueba reciben una URL de marcador de posición (test: true); no se sube ni se almacena nada. |
| `method` | `"PUT"` | Sí |  |
| `headers` | objeto de cadenas | Sí |  |
| `expires_at` | entero | Sí | Marca de tiempo Unix. |
| `test` | `true` | No |  |

#### Códigos de error

| Código | Estado |
| --- | --- |
| `not_found` | 404 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Ejemplo

**Solicitud: cURL**

```bash
curl https://api.fileverity.com/v1/files/file_8Hk2pQ4vN9sL1xR7cW3mY6zB \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"
```

**Respuesta**

```json
{
  "id": "file_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "file",
  "filename": "claim-photo.jpg",
  "bytes": 2481920,
  "content_type": "image/jpeg",
  "status": "uploaded",
  "livemode": true,
  "created": 1793700000,
  "expires_at": 1793786400
}
```

### Eliminar un archivo

`DELETE` `https://api.fileverity.com/v1/files/{id}`

Elimina un archivo subido y sus bytes almacenados.

#### Parámetros

| Nombre | Ubicación | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- | --- |
| `id` | ruta | cadena | Sí | ID del archivo. |

#### Respuestas

| Estado | Descripción | Cuerpo |
| --- | --- | --- |
| 200 | El archivo se eliminó. | `FileDeleted` |
| 401 | Clave de API ausente o no válida. Códigos de error: missing_api_key, invalid_api_key. | `Error` |
| 404 | Recurso no encontrado. Códigos de error: not_found. | `Error` |
| 429 | Demasiadas solicitudes. Códigos de error: rate_limited. | `Error` |
| 500 | Error interno; no se cobra. Códigos de error: internal_error. | `Error` |

#### Respuesta 200: FileDeleted

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | cadena | Sí |  |
| `object` | `"file"` | Sí |  |
| `deleted` | `true` | Sí |  |

#### Códigos de error

| Código | Estado |
| --- | --- |
| `not_found` | 404 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Ejemplo

**Solicitud: cURL**

```bash
curl -X DELETE https://api.fileverity.com/v1/files/file_8Hk2pQ4vN9sL1xR7cW3mY6zB \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"
```

**Respuesta**

```json
{
  "id": "file_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "file",
  "deleted": true
}
```

## Análisis

### Crear un análisis

`POST` `https://api.fileverity.com/v1/analyses`

Analiza un archivo subido con fvimg-2 (imágenes) o fvdoc-3 (documentos). Un análisis es una comprobación de imagen o de documento. La respuesta es 202 con el estado processing; el resultado llega por webhook o consultando periódicamente GET /analyses/{id}. Envíe Prefer: wait=N (hasta 60 segundos) para mantener la solicitud abierta hasta que el resultado esté listo; un análisis terminado devuelve 200. El precio se reserva cuando se crea el análisis y se libera si falla o se cancela. Los resultados se conservan 7 días. Cuando la capacidad está ocupada, la API devuelve 503 service_unavailable con un encabezado retry-after y no cobra nada: reintente con la misma Idempotency-Key y ejecute los análisis de imágenes uno tras otro para obtener el mejor rendimiento. Las claves de prueba devuelven un resultado de ejemplo y nunca se cobran; el informe de ejemplo solo contiene unos pocos campos.

#### Parámetros

| Nombre | Ubicación | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | encabezado | cadena | No | Clave única de hasta 255 caracteres. Repetir la solicitud con la misma clave y el mismo cuerpo en un plazo de 24 horas devuelve la primera respuesta con el encabezado idempotent-replayed: true; la misma clave con un cuerpo distinto devuelve 409. |
| `Prefer` | encabezado | cadena | No | wait=N mantiene la solicitud abierta hasta N segundos (máximo 60) o hasta que termina el análisis. |

#### Cuerpo de la solicitud: application/json, obligatorio

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `model` | uno de `"fvimg-2"`, `"fvimg-2-2026-10-30"`, `"fvdoc-3"`, `"fvdoc-3-2026-11-03"` | Sí | ID de modelo o ID de versión fechada. fvimg-2 analiza imágenes y fvdoc-3, documentos. |
| `file` | cadena | Sí | ID de un archivo subido. |
| `metadata` | objeto de cadenas | No | Hasta 16 pares de cadenas (claves de hasta 40 caracteres, valores de hasta 500) que se devuelven en el análisis y en los webhooks. |
| `options` | objeto | No |  |

**options: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `password` | cadena | No | Contraseña de un documento cifrado. Longitud máxima 256. |
| `locale` | uno de `"en"`, `"fr"`, `"de"`, `"es"`, `"zh"`, `"vi"`, `"ar"` | No | Idioma de los hallazgos del documento. Valor predeterminado: `"en"`. |

#### Respuestas

| Estado | Descripción | Cuerpo |
| --- | --- | --- |
| 200 | El análisis terminado. | `Analysis` |
| 202 | El análisis se está procesando. | `Analysis` |
| 400 | Solicitud no válida. Códigos de error: invalid_json, missing_parameter, file_not_found, invalid_parameter. | `Error` |
| 401 | Clave de API ausente o no válida. Códigos de error: missing_api_key, invalid_api_key. | `Error` |
| 402 | El saldo o el límite de gasto mensual de la clave no cubre la solicitud. Códigos de error: insufficient_balance, spend_limit_reached. | `Error` |
| 404 | Recurso no encontrado. Códigos de error: model_not_found. | `Error` |
| 409 | Conflicto con el estado actual. Códigos de error: idempotency_mismatch, idempotency_in_progress. | `Error` |
| 413 | Se superó un límite de tamaño. Códigos de error: file_too_large, too_many_pixels, too_many_pages, document_too_long. | `Error` |
| 415 | Tipo de medio o formato de archivo no admitido. Códigos de error: unsupported_media_type, unsupported_file. | `Error` |
| 422 | No se puede procesar el archivo. Códigos de error: invalid_file, password_required, wrong_password, not_examinable. | `Error` |
| 429 | Demasiadas solicitudes. Códigos de error: rate_limited. | `Error` |
| 500 | Error interno; no se cobra. Códigos de error: internal_error. | `Error` |
| 502 | No se pudo completar el análisis; no se cobra. Códigos de error: analysis_failed. | `Error` |
| 503 | No disponible temporalmente u ocupado; no se cobra. Reintente tras el número de segundos que indica el encabezado retry-after. Códigos de error: service_unavailable. | `Error` |

#### Respuesta 200: Analysis

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | cadena | Sí |  |
| `object` | `"analysis"` | Sí |  |
| `created` | entero | Sí | Marca de tiempo Unix. |
| `model` | cadena | Sí | Versión fechada que produjo el resultado. |
| `livemode` | booleano | Sí |  |
| `status` | uno de `"processing"`, `"succeeded"`, `"failed"`, `"canceled"` | Sí |  |
| `file` | objeto | Sí |  |
| `report_id` | cadena o null | Sí | ID de informe verificable, FV-XXXX-XXXX-XXXX. |
| `report_url` | cadena o null | Sí | Página de verificación pública del informe. |
| `summary` | `ImageSummary` o `DocumentSummary` o null | Sí | El veredicto breve y estable: un ImageSummary para imágenes, un DocumentSummary para documentos, null hasta que el análisis termina con éxito. |
| `result` | objeto o null | Sí | Presente cuando status es succeeded y hasta que caduca el resultado. |
| `error` | objeto o null | Sí |  |
| `progress` | objeto o null | Sí |  |
| `usage` | objeto | Sí |  |
| `metadata` | objeto o null | Sí |  |
| `completed_at` | entero o null | Sí |  |
| `expires_at` | entero o null | Sí | Marca de tiempo Unix a partir de la cual se elimina el resultado. |

**file: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `name` | cadena o null | No |  |
| `bytes` | entero o null | No |  |
| `format` | cadena o null | No |  |

**summary (ImageSummary): campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `level` | uno de `"L0"`, `"L1"`, `"L2"`, `"L3"`, `"L4"`, `"L5"` | Sí | Nivel de riesgo, de L0 a L5. |
| `assessment` | uno de `"authentic_untouched"`, `"authentic_locally_edited"`, `"ai_generated"`, `"undetermined"` | Sí |  |
| `action` | uno de `"accept"`, `"review"`, `"reject"`, `"resubmit"` | Sí |  |
| `ai` | uno de `"labelled"`, `"very_likely"`, `"suspected"`, `"undecided"`, `"low"`, `"very_low"`, `"not_evaluated"` | Sí | El hallazgo sobre la generación con IA. |
| `edit` | uno de `"detected"`, `"suspected"`, `"suspected_record"`, `"review"`, `"generative"`, `"minor"`, `"none"`, `"not_applicable"`, `"not_evaluated"` | Sí | El hallazgo sobre la edición local. |

**summary (DocumentSummary): campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `kind` | `"docpro"` | Sí |  |
| `level` | uno de `"L0"`, `"L1"`, `"L2"`, `"L3"`, `"L4"`, `"L5"` | Sí | Nivel de riesgo, de L0 a L5. |
| `action` | uno de `"accept"`, `"note"`, `"review"`, `"reject"`, `"resubmit"` | Sí | note: revise el contenido de IA señalado en el informe según su política. |
| `reason` | cadena o null | Sí | El hallazgo o la condición que hay detrás del nivel, por ejemplo clean o incomplete, o un ID de hallazgo. |
| `findings` | array de cadenas | Sí | ID de los hallazgos relevantes. |
| `pages` | entero | Sí | Páginas del documento. |
| `images` | entero | Sí | Fotos incrustadas examinadas. |
| `text` | uno de `"ai_generated"`, `"mixed"`, `"human"`, `"inconclusive"`, `null` | Sí | El veredicto sobre el texto del documento, o null cuando no se evaluó el texto. |
| `strong` | `true` | No | Presente cuando un hallazgo de la lista es sólido. |

**result: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `report` | `ImageReport` o `DocumentReport` | No | El informe completo. report.schema es fileverity.report/1 para imágenes y fileverity.docpro/1 para documentos. |
| `stamped_at` | entero o null | No | Marca de tiempo Unix de la marca de tiempo RFC 3161 emitida para el informe, o null. |

**report (ImageReport): campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `schema` | `"fileverity.report/1"` | Sí |  |
| `id` | cadena | Sí | ID del informe, FV-XXXX-XXXX-XXXX. |
| `sample` | `true` | No | Presente en los informes de ejemplo fijos que devuelven las claves de prueba. |
| `issuedAt` | cadena | No | Cuándo se emitió el informe, en ISO 8601 y UTC. Formato date-time. |
| `issuer` | objeto | No | Quién emitió el informe. |
| `file` | objeto | No | La imagen comprobada. |
| `pro` | objeto | No | El veredicto. Los mismos valores que summary, con reason. |
| `score` | entero o null | No | Puntuación de autenticidad de 0 a 100 en pasos de 5: en qué medida las pruebas respaldan que la imagen es una captura auténtica y sin editar. null cuando no se evaluó. |
| `confidence` | uno de `"high"`, `"medium"`, `"low"` | No | Hasta qué punto este archivo permite que el análisis llegue a conclusiones. Una confianza baja suele deberse al propio archivo, por ejemplo, a una resolución baja o a una compresión intensa. |
| `questions` | objeto | No | Las tres preguntas a las que responde el informe. |
| `generator` | objeto o null | No | El generador de IA identificado para la imagen, o null. |
| `regions` | array de objetos | No | Regiones marcadas, en píxeles de la imagen mostrada. |
| `provenance` | objeto | No | Lo que dicen los propios registros del archivo sobre su origen. |
| `digest` | cadena | No | Huella del contenido del informe, que usa la página de verificación. |

**issuer: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `name` | cadena | No |  |
| `operator` | cadena | No |  |
| `verify` | cadena | No | Página de verificación pública del informe. |

**file: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `name` | cadena o null | No |  |
| `sha256` | cadena | No | SHA-256 del archivo comprobado, en hexadecimal. |
| `bytes` | entero | No |  |
| `width` | entero | No | Ancho en píxeles tal como se muestra. |
| `height` | entero | No | Alto en píxeles tal como se muestra. |
| `format` | cadena | No |  |

**pro: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `level` | uno de `"L0"`, `"L1"`, `"L2"`, `"L3"`, `"L4"`, `"L5"` | No | Nivel de riesgo, de L0 a L5. |
| `action` | uno de `"accept"`, `"review"`, `"reject"`, `"resubmit"` | No |  |
| `assessment` | uno de `"authentic_untouched"`, `"authentic_locally_edited"`, `"ai_generated"`, `"undetermined"` | No |  |
| `reason` | cadena o null | No |  |

**questions: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `ai` | objeto | No |  |
| `edit` | objeto | No |  |
| `source` | objeto | No |  |

**ai: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `key` | uno de `"labelled"`, `"very_likely"`, `"suspected"`, `"undecided"`, `"low"`, `"very_low"`, `"not_evaluated"` | No |  |
| `basis` | uno de `"verified"`, `"detected"`, `"declared"`, `null` | No | En qué se basa la respuesta. |
| `strength` | uno de `"strong"`, `"moderate"`, `"limited"`, `null` | No | Con qué solidez respalda la evidencia la respuesta. |
| `likelihood` | entero o null | No | Probabilidad de generación con IA de 0 a 100 en pasos de 5, o null. |

**edit: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `key` | uno de `"detected"`, `"suspected"`, `"suspected_record"`, `"review"`, `"generative"`, `"minor"`, `"none"`, `"not_applicable"`, `"not_evaluated"` | No |  |
| `basis` | uno de `"verified"`, `"detected"`, `"declared"`, `null` | No | En qué se basa la respuesta. |
| `strength` | uno de `"strong"`, `"moderate"`, `"limited"`, `null` | No | Con qué solidez respalda la evidencia la respuesta. |
| `regions` | entero | No | Número de regiones marcadas. |

**source: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `key` | cadena | No |  |
| `basis` | uno de `"verified"`, `"detected"`, `"declared"`, `null` | No | En qué se basa la respuesta. |
| `strength` | uno de `"strong"`, `"moderate"`, `"limited"`, `null` | No | Con qué solidez respalda la evidencia la respuesta. |
| `signer` | cadena o null | No |  |
| `aiClaim` | booleano | No | Indica si los registros del propio archivo declaran que se generó con IA. |

**generator: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `name` | cadena | No |  |
| `basis` | cadena | No | Cómo se identificó el generador. |

**regions: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | cadena | No |  |
| `x` | entero | No |  |
| `y` | entero | No |  |
| `w` | entero | No |  |
| `h` | entero | No |  |
| `strength` | uno de `"high"`, `"medium"` | No |  |

**provenance: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `credentials` | uno de `"valid"`, `"unverified"`, `"issues"`, `"invalid"`, `"removed"`, `"none"` | No | Estado de las Credenciales de contenido. |
| `signer` | cadena o null | No |  |
| `software` | array de cadenas | No | Software citado en los registros del archivo. |
| `camera` | cadena o null | No |  |
| `captured` | cadena o null | No | Hora de captura registrada en el archivo, si la hay. |

**report (DocumentReport): campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `schema` | `"fileverity.docpro/1"` | Sí |  |
| `id` | cadena | Sí | ID del informe, FV-XXXX-XXXX-XXXX. |
| `sample` | `true` | No | Presente en los informes de ejemplo fijos que devuelven las claves de prueba. |
| `issuedAt` | cadena | No | Cuándo se emitió el informe, en ISO 8601 y UTC. Formato date-time. |
| `receivedAt` | cadena | No | Cuándo se recibió el archivo, en ISO 8601 y UTC. Formato date-time. |
| `issuer` | objeto | No | Quién emitió el informe. |
| `file` | objeto | No | El documento comprobado. |
| `level` | uno de `"L0"`, `"L1"`, `"L2"`, `"L3"`, `"L4"`, `"L5"` | No | Nivel de riesgo, de L0 a L5. |
| `action` | uno de `"accept"`, `"note"`, `"review"`, `"reject"`, `"resubmit"` | No |  |
| `reason` | cadena o null | No | El hallazgo o la condición que determina el nivel. |
| `findings` | array de objetos | No | Los hallazgos que determinan el nivel, cada uno con las páginas y las fotos incrustadas a las que se refiere. |
| `text` | objeto | No | El resultado para el texto del documento. |
| `images` | array de objetos | No | Las fotos y los gráficos incrustados, numerados en el orden del documento. |
| `structure` | objeto o null | No | El historial de ediciones del archivo, o null si no se examinó. |
| `provenance` | objeto | No | Lo que dicen los propios registros del archivo sobre su origen. |
| `digest` | cadena | No | Huella del contenido del informe, que usa la página de verificación. |

**issuer: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `name` | cadena | No |  |
| `operator` | cadena | No |  |
| `verify` | cadena | No | Página de verificación pública del informe. |

**file: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `name` | cadena o null | No |  |
| `sha256` | cadena | No | SHA-256 del archivo comprobado, en hexadecimal. |
| `bytes` | entero | No |  |
| `format` | cadena | No |  |
| `pages` | entero | No |  |
| `textLayer` | uno de `"present"`, `"partial"`, `"absent"` | No | Indica si el documento incluye una capa de texto. |

**findings: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | cadena | No |  |
| `basis` | uno de `"verified"`, `"detected"`, `"declared"` | No |  |
| `strength` | uno de `"strong"`, `"moderate"`, `"limited"` | No |  |
| `material` | booleano | No | Indica si el hallazgo cuenta para el nivel. |
| `pages` | array de enteros | No |  |
| `images` | array de enteros | No |  |

**text: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `status` | uno de `"evaluated"`, `"insufficient_text"`, `"unsupported_language"`, `"no_text"` | No |  |
| `verdict` | uno de `"ai_generated"`, `"mixed"`, `"human"`, `"inconclusive"` | No | Presente cuando status es evaluated. |
| `words` | entero | No |  |
| `languages` | array de cadenas | No |  |
| `passages` | entero | No | Número de pasajes señalados. |

**images: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `n` | entero | No |  |
| `pages` | array de enteros | No |  |
| `kind` | uno de `"photo"`, `"graphic"` | No |  |
| `width` | entero | No |  |
| `height` | entero | No |  |
| `level` | uno de `"L0"`, `"L1"`, `"L2"`, `"L3"`, `"L4"`, `"L5"`, `null` | No |  |
| `assessment` | uno de `"authentic_untouched"`, `"authentic_locally_edited"`, `"ai_generated"`, `"undetermined"`, `null` | No |  |
| `ai` | uno de `"labelled"`, `"very_likely"`, `"suspected"`, `"undecided"`, `"low"`, `"very_low"`, `"not_evaluated"`, `null` | No |  |
| `edit` | uno de `"detected"`, `"suspected"`, `"suspected_record"`, `"review"`, `"generative"`, `"minor"`, `"none"`, `"not_applicable"`, `"not_evaluated"`, `null` | No |  |

**structure: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `revisions` | entero o null | No |  |
| `changedPages` | array de enteros | No |  |
| `addedPages` | entero | No |  |
| `signatures` | entero | No |  |

**provenance: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `credentials` | cadena | No | Estado de las Credenciales de contenido. |
| `signer` | cadena o null | No |  |
| `aiClaim` | booleano | No | Indica si los registros del propio archivo declaran que se generó con IA. |
| `software` | array de cadenas | No |  |
| `created` | cadena o null | No |  |
| `modified` | cadena o null | No |  |
| `revisions` | entero o null | No |  |
| `signed` | booleano o null | No |  |

**error: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `code` | uno de `"invalid_json"`, `"missing_parameter"`, `"invalid_parameter"`, `"text_too_short"`, `"text_too_long"`, `"unsupported_media_type"`, `"unsupported_language"`, `"file_not_found"`, `"unsupported_file"`, `"file_too_large"`, `"too_many_pixels"`, `"too_many_pages"`, `"document_too_long"`, `"invalid_file"`, `"password_required"`, `"wrong_password"`, `"not_examinable"`, `"missing_api_key"`, `"invalid_api_key"`, `"insufficient_balance"`, `"spend_limit_reached"`, `"not_found"`, `"model_not_found"`, `"not_cancelable"`, `"canceled"`, `"idempotency_mismatch"`, `"idempotency_in_progress"`, `"pending_files_limit"`, `"rate_limited"`, `"internal_error"`, `"analysis_failed"`, `"service_unavailable"` | No |  |
| `message` | cadena | No |  |

**progress: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `stage` | uno de `"queued"`, `"reading"`, `"analyzing"`, `"reporting"` | No |  |
| `done` | entero | No | Unidades terminadas en la fase actual, cuando se conocen; en caso contrario, 0. |
| `total` | entero | No | Unidades de la fase actual, cuando se conocen; en caso contrario, 0. |
| `position` | entero | No | Posición en la cola mientras la fase es queued. |

**usage: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `amount` | entero | No | Cargo en centavos; 0 en las comprobaciones del inicio gratuito y en los fallos. |
| `currency` | `"usd"` | No |  |
| `funding` | uno de `"trial"`, `"balance"`, `null` | No |  |

#### Códigos de error

| Código | Estado |
| --- | --- |
| `invalid_json` | 400 |
| `missing_parameter` | 400 |
| `unsupported_media_type` | 415 |
| `model_not_found` | 404 |
| `file_not_found` | 400 |
| `unsupported_file` | 415 |
| `invalid_file` | 422 |
| `file_too_large` | 413 |
| `too_many_pixels` | 413 |
| `too_many_pages` | 413 |
| `document_too_long` | 413 |
| `password_required` | 422 |
| `wrong_password` | 422 |
| `not_examinable` | 422 |
| `insufficient_balance` | 402 |
| `spend_limit_reached` | 402 |
| `service_unavailable` | 503 |
| `analysis_failed` | 502 |
| `invalid_parameter` | 400 |
| `idempotency_mismatch` | 409 |
| `idempotency_in_progress` | 409 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Ejemplo

**Solicitud: cURL**

```bash
curl https://api.fileverity.com/v1/analyses \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -d '{"model": "fvimg-2", "file": "file_8Hk2pQ4vN9sL1xR7cW3mY6zB"}'
```

**Respuesta**

```json
{
  "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "analysis",
  "created": 1793700120,
  "model": "fvimg-2-2026-10-30",
  "livemode": true,
  "status": "succeeded",
  "file": {
    "name": "claim-photo.jpg",
    "bytes": 2481920,
    "format": "jpeg"
  },
  "report_id": "FV-7K2M-9QXD-4T8R",
  "report_url": "https://fileverity.com/verify/FV-7K2M-9QXD-4T8R",
  "summary": {
    "level": "L2",
    "assessment": "authentic_untouched",
    "action": "accept",
    "ai": "very_low",
    "edit": "none"
  },
  "result": {
    "report": {
      "schema": "fileverity.report/1",
      "id": "FV-7K2M-9QXD-4T8R"
    },
    "stamped_at": 1793700130
  },
  "error": null,
  "progress": null,
  "usage": {
    "amount": 199,
    "currency": "usd",
    "funding": "balance"
  },
  "metadata": {
    "order_id": "A-10492"
  },
  "completed_at": 1793700131,
  "expires_at": 1794304931
}
```

### Listar análisis

`GET` `https://api.fileverity.com/v1/analyses`

Lista los análisis de imágenes y documentos de su espacio de trabajo, del más reciente al más antiguo. Las claves de prueba siempre reciben una lista vacía.

#### Parámetros

| Nombre | Ubicación | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- | --- |
| `limit` | consulta | entero | No | Valor predeterminado: `20`. Mínimo 1. Máximo 100. |
| `starting_after` | consulta | cadena | No | Cursor: el next_cursor de la página anterior. |
| `type` | consulta | uno de `"image"`, `"document"` | No |  |

#### Respuestas

| Estado | Descripción | Cuerpo |
| --- | --- | --- |
| 200 | Una página de análisis. | `AnalysisList` |
| 400 | Solicitud no válida. Códigos de error: invalid_parameter. | `Error` |
| 401 | Clave de API ausente o no válida. Códigos de error: missing_api_key, invalid_api_key. | `Error` |
| 429 | Demasiadas solicitudes. Códigos de error: rate_limited. | `Error` |
| 500 | Error interno; no se cobra. Códigos de error: internal_error. | `Error` |

#### Respuesta 200: AnalysisList

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `object` | `"list"` | Sí |  |
| `data` | array de `Analysis` | Sí |  |
| `has_more` | booleano | Sí |  |
| `next_cursor` | cadena o null | Sí | Páselo como starting_after para obtener la página siguiente. |

**data: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | cadena | Sí |  |
| `object` | `"analysis"` | Sí |  |
| `created` | entero | Sí | Marca de tiempo Unix. |
| `model` | cadena | Sí | Versión fechada que produjo el resultado. |
| `livemode` | booleano | Sí |  |
| `status` | uno de `"processing"`, `"succeeded"`, `"failed"`, `"canceled"` | Sí |  |
| `file` | objeto | Sí |  |
| `report_id` | cadena o null | Sí | ID de informe verificable, FV-XXXX-XXXX-XXXX. |
| `report_url` | cadena o null | Sí | Página de verificación pública del informe. |
| `summary` | `ImageSummary` o `DocumentSummary` o null | Sí | El veredicto breve y estable: un ImageSummary para imágenes, un DocumentSummary para documentos, null hasta que el análisis termina con éxito. |
| `result` | objeto o null | Sí | Presente cuando status es succeeded y hasta que caduca el resultado. |
| `error` | objeto o null | Sí |  |
| `progress` | objeto o null | Sí |  |
| `usage` | objeto | Sí |  |
| `metadata` | objeto o null | Sí |  |
| `completed_at` | entero o null | Sí |  |
| `expires_at` | entero o null | Sí | Marca de tiempo Unix a partir de la cual se elimina el resultado. |

**file: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `name` | cadena o null | No |  |
| `bytes` | entero o null | No |  |
| `format` | cadena o null | No |  |

**result: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `report` | `ImageReport` o `DocumentReport` | No | El informe completo. report.schema es fileverity.report/1 para imágenes y fileverity.docpro/1 para documentos. |
| `stamped_at` | entero o null | No | Marca de tiempo Unix de la marca de tiempo RFC 3161 emitida para el informe, o null. |

**error: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `code` | uno de `"invalid_json"`, `"missing_parameter"`, `"invalid_parameter"`, `"text_too_short"`, `"text_too_long"`, `"unsupported_media_type"`, `"unsupported_language"`, `"file_not_found"`, `"unsupported_file"`, `"file_too_large"`, `"too_many_pixels"`, `"too_many_pages"`, `"document_too_long"`, `"invalid_file"`, `"password_required"`, `"wrong_password"`, `"not_examinable"`, `"missing_api_key"`, `"invalid_api_key"`, `"insufficient_balance"`, `"spend_limit_reached"`, `"not_found"`, `"model_not_found"`, `"not_cancelable"`, `"canceled"`, `"idempotency_mismatch"`, `"idempotency_in_progress"`, `"pending_files_limit"`, `"rate_limited"`, `"internal_error"`, `"analysis_failed"`, `"service_unavailable"` | No |  |
| `message` | cadena | No |  |

**progress: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `stage` | uno de `"queued"`, `"reading"`, `"analyzing"`, `"reporting"` | No |  |
| `done` | entero | No | Unidades terminadas en la fase actual, cuando se conocen; en caso contrario, 0. |
| `total` | entero | No | Unidades de la fase actual, cuando se conocen; en caso contrario, 0. |
| `position` | entero | No | Posición en la cola mientras la fase es queued. |

**usage: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `amount` | entero | No | Cargo en centavos; 0 en las comprobaciones del inicio gratuito y en los fallos. |
| `currency` | `"usd"` | No |  |
| `funding` | uno de `"trial"`, `"balance"`, `null` | No |  |

#### Códigos de error

| Código | Estado |
| --- | --- |
| `invalid_parameter` | 400 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Ejemplo

**Solicitud: cURL**

```bash
curl "https://api.fileverity.com/v1/analyses?limit=20&type=image" \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"
```

**Respuesta**

```json
{
  "object": "list",
  "data": [
    {
      "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",
      "object": "analysis",
      "created": 1793700120,
      "model": "fvimg-2-2026-10-30",
      "livemode": true,
      "status": "succeeded",
      "file": {
        "name": "claim-photo.jpg",
        "bytes": 2481920,
        "format": "jpeg"
      },
      "report_id": "FV-7K2M-9QXD-4T8R",
      "report_url": "https://fileverity.com/verify/FV-7K2M-9QXD-4T8R",
      "summary": {
        "level": "L2",
        "assessment": "authentic_untouched",
        "action": "accept",
        "ai": "very_low",
        "edit": "none"
      },
      "result": {
        "report": {
          "schema": "fileverity.report/1",
          "id": "FV-7K2M-9QXD-4T8R"
        },
        "stamped_at": 1793700130
      },
      "error": null,
      "progress": null,
      "usage": {
        "amount": 199,
        "currency": "usd",
        "funding": "balance"
      },
      "metadata": {
        "order_id": "A-10492"
      },
      "completed_at": 1793700131,
      "expires_at": 1794304931
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

### Recuperar un análisis

`GET` `https://api.fileverity.com/v1/analyses/{id}`

Devuelve el análisis, con su resultado una vez que ha terminado con éxito y hasta que caduque.

#### Parámetros

| Nombre | Ubicación | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- | --- |
| `id` | ruta | cadena | Sí | ID del análisis. |

#### Respuestas

| Estado | Descripción | Cuerpo |
| --- | --- | --- |
| 200 | El análisis. | `Analysis` |
| 401 | Clave de API ausente o no válida. Códigos de error: missing_api_key, invalid_api_key. | `Error` |
| 404 | Recurso no encontrado. Códigos de error: not_found. | `Error` |
| 429 | Demasiadas solicitudes. Códigos de error: rate_limited. | `Error` |
| 500 | Error interno; no se cobra. Códigos de error: internal_error. | `Error` |

#### Respuesta 200: Analysis

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | cadena | Sí |  |
| `object` | `"analysis"` | Sí |  |
| `created` | entero | Sí | Marca de tiempo Unix. |
| `model` | cadena | Sí | Versión fechada que produjo el resultado. |
| `livemode` | booleano | Sí |  |
| `status` | uno de `"processing"`, `"succeeded"`, `"failed"`, `"canceled"` | Sí |  |
| `file` | objeto | Sí |  |
| `report_id` | cadena o null | Sí | ID de informe verificable, FV-XXXX-XXXX-XXXX. |
| `report_url` | cadena o null | Sí | Página de verificación pública del informe. |
| `summary` | `ImageSummary` o `DocumentSummary` o null | Sí | El veredicto breve y estable: un ImageSummary para imágenes, un DocumentSummary para documentos, null hasta que el análisis termina con éxito. |
| `result` | objeto o null | Sí | Presente cuando status es succeeded y hasta que caduca el resultado. |
| `error` | objeto o null | Sí |  |
| `progress` | objeto o null | Sí |  |
| `usage` | objeto | Sí |  |
| `metadata` | objeto o null | Sí |  |
| `completed_at` | entero o null | Sí |  |
| `expires_at` | entero o null | Sí | Marca de tiempo Unix a partir de la cual se elimina el resultado. |

**file: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `name` | cadena o null | No |  |
| `bytes` | entero o null | No |  |
| `format` | cadena o null | No |  |

**result: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `report` | `ImageReport` o `DocumentReport` | No | El informe completo. report.schema es fileverity.report/1 para imágenes y fileverity.docpro/1 para documentos. |
| `stamped_at` | entero o null | No | Marca de tiempo Unix de la marca de tiempo RFC 3161 emitida para el informe, o null. |

**error: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `code` | uno de `"invalid_json"`, `"missing_parameter"`, `"invalid_parameter"`, `"text_too_short"`, `"text_too_long"`, `"unsupported_media_type"`, `"unsupported_language"`, `"file_not_found"`, `"unsupported_file"`, `"file_too_large"`, `"too_many_pixels"`, `"too_many_pages"`, `"document_too_long"`, `"invalid_file"`, `"password_required"`, `"wrong_password"`, `"not_examinable"`, `"missing_api_key"`, `"invalid_api_key"`, `"insufficient_balance"`, `"spend_limit_reached"`, `"not_found"`, `"model_not_found"`, `"not_cancelable"`, `"canceled"`, `"idempotency_mismatch"`, `"idempotency_in_progress"`, `"pending_files_limit"`, `"rate_limited"`, `"internal_error"`, `"analysis_failed"`, `"service_unavailable"` | No |  |
| `message` | cadena | No |  |

**progress: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `stage` | uno de `"queued"`, `"reading"`, `"analyzing"`, `"reporting"` | No |  |
| `done` | entero | No | Unidades terminadas en la fase actual, cuando se conocen; en caso contrario, 0. |
| `total` | entero | No | Unidades de la fase actual, cuando se conocen; en caso contrario, 0. |
| `position` | entero | No | Posición en la cola mientras la fase es queued. |

**usage: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `amount` | entero | No | Cargo en centavos; 0 en las comprobaciones del inicio gratuito y en los fallos. |
| `currency` | `"usd"` | No |  |
| `funding` | uno de `"trial"`, `"balance"`, `null` | No |  |

#### Códigos de error

| Código | Estado |
| --- | --- |
| `not_found` | 404 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Ejemplo

**Solicitud: cURL**

```bash
curl https://api.fileverity.com/v1/analyses/an_8Hk2pQ4vN9sL1xR7cW3mY6zB \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"
```

**Respuesta**

```json
{
  "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "analysis",
  "created": 1793700120,
  "model": "fvimg-2-2026-10-30",
  "livemode": true,
  "status": "succeeded",
  "file": {
    "name": "claim-photo.jpg",
    "bytes": 2481920,
    "format": "jpeg"
  },
  "report_id": "FV-7K2M-9QXD-4T8R",
  "report_url": "https://fileverity.com/verify/FV-7K2M-9QXD-4T8R",
  "summary": {
    "level": "L2",
    "assessment": "authentic_untouched",
    "action": "accept",
    "ai": "very_low",
    "edit": "none"
  },
  "result": {
    "report": {
      "schema": "fileverity.report/1",
      "id": "FV-7K2M-9QXD-4T8R"
    },
    "stamped_at": 1793700130
  },
  "error": null,
  "progress": null,
  "usage": {
    "amount": 199,
    "currency": "usd",
    "funding": "balance"
  },
  "metadata": {
    "order_id": "A-10492"
  },
  "completed_at": 1793700131,
  "expires_at": 1794304931
}
```

### Cancelar un análisis

`POST` `https://api.fileverity.com/v1/analyses/{id}/cancel`

Cancela un análisis de documento que aún se está procesando y libera su cargo. Los análisis de imágenes no se pueden cancelar una vez creados.

#### Parámetros

| Nombre | Ubicación | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- | --- |
| `id` | ruta | cadena | Sí | ID del análisis. |
| `Idempotency-Key` | encabezado | cadena | No | Clave única de hasta 255 caracteres. Repetir la solicitud con la misma clave y el mismo cuerpo en un plazo de 24 horas devuelve la primera respuesta con el encabezado idempotent-replayed: true; la misma clave con un cuerpo distinto devuelve 409. |

#### Respuestas

| Estado | Descripción | Cuerpo |
| --- | --- | --- |
| 200 | El análisis cancelado. | `Analysis` |
| 400 | Solicitud no válida. Códigos de error: invalid_parameter. | `Error` |
| 401 | Clave de API ausente o no válida. Códigos de error: missing_api_key, invalid_api_key. | `Error` |
| 404 | Recurso no encontrado. Códigos de error: not_found. | `Error` |
| 409 | Conflicto con el estado actual. Códigos de error: not_cancelable, idempotency_mismatch, idempotency_in_progress. | `Error` |
| 429 | Demasiadas solicitudes. Códigos de error: rate_limited. | `Error` |
| 500 | Error interno; no se cobra. Códigos de error: internal_error. | `Error` |

#### Respuesta 200: Analysis

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | cadena | Sí |  |
| `object` | `"analysis"` | Sí |  |
| `created` | entero | Sí | Marca de tiempo Unix. |
| `model` | cadena | Sí | Versión fechada que produjo el resultado. |
| `livemode` | booleano | Sí |  |
| `status` | uno de `"processing"`, `"succeeded"`, `"failed"`, `"canceled"` | Sí |  |
| `file` | objeto | Sí |  |
| `report_id` | cadena o null | Sí | ID de informe verificable, FV-XXXX-XXXX-XXXX. |
| `report_url` | cadena o null | Sí | Página de verificación pública del informe. |
| `summary` | `ImageSummary` o `DocumentSummary` o null | Sí | El veredicto breve y estable: un ImageSummary para imágenes, un DocumentSummary para documentos, null hasta que el análisis termina con éxito. |
| `result` | objeto o null | Sí | Presente cuando status es succeeded y hasta que caduca el resultado. |
| `error` | objeto o null | Sí |  |
| `progress` | objeto o null | Sí |  |
| `usage` | objeto | Sí |  |
| `metadata` | objeto o null | Sí |  |
| `completed_at` | entero o null | Sí |  |
| `expires_at` | entero o null | Sí | Marca de tiempo Unix a partir de la cual se elimina el resultado. |

**file: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `name` | cadena o null | No |  |
| `bytes` | entero o null | No |  |
| `format` | cadena o null | No |  |

**result: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `report` | `ImageReport` o `DocumentReport` | No | El informe completo. report.schema es fileverity.report/1 para imágenes y fileverity.docpro/1 para documentos. |
| `stamped_at` | entero o null | No | Marca de tiempo Unix de la marca de tiempo RFC 3161 emitida para el informe, o null. |

**error: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `code` | uno de `"invalid_json"`, `"missing_parameter"`, `"invalid_parameter"`, `"text_too_short"`, `"text_too_long"`, `"unsupported_media_type"`, `"unsupported_language"`, `"file_not_found"`, `"unsupported_file"`, `"file_too_large"`, `"too_many_pixels"`, `"too_many_pages"`, `"document_too_long"`, `"invalid_file"`, `"password_required"`, `"wrong_password"`, `"not_examinable"`, `"missing_api_key"`, `"invalid_api_key"`, `"insufficient_balance"`, `"spend_limit_reached"`, `"not_found"`, `"model_not_found"`, `"not_cancelable"`, `"canceled"`, `"idempotency_mismatch"`, `"idempotency_in_progress"`, `"pending_files_limit"`, `"rate_limited"`, `"internal_error"`, `"analysis_failed"`, `"service_unavailable"` | No |  |
| `message` | cadena | No |  |

**progress: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `stage` | uno de `"queued"`, `"reading"`, `"analyzing"`, `"reporting"` | No |  |
| `done` | entero | No | Unidades terminadas en la fase actual, cuando se conocen; en caso contrario, 0. |
| `total` | entero | No | Unidades de la fase actual, cuando se conocen; en caso contrario, 0. |
| `position` | entero | No | Posición en la cola mientras la fase es queued. |

**usage: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `amount` | entero | No | Cargo en centavos; 0 en las comprobaciones del inicio gratuito y en los fallos. |
| `currency` | `"usd"` | No |  |
| `funding` | uno de `"trial"`, `"balance"`, `null` | No |  |

#### Códigos de error

| Código | Estado |
| --- | --- |
| `not_found` | 404 |
| `not_cancelable` | 409 |
| `invalid_parameter` | 400 |
| `idempotency_mismatch` | 409 |
| `idempotency_in_progress` | 409 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Ejemplo

**Solicitud: cURL**

```bash
curl -X POST https://api.fileverity.com/v1/analyses/an_8Hk2pQ4vN9sL1xR7cW3mY6zB/cancel \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"
```

**Respuesta**

```json
{
  "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "analysis",
  "created": 1793700120,
  "model": "fvimg-2-2026-10-30",
  "livemode": true,
  "status": "canceled",
  "file": {
    "name": "claim-photo.jpg",
    "bytes": 2481920,
    "format": "jpeg"
  },
  "report_id": null,
  "report_url": null,
  "summary": null,
  "result": null,
  "error": {
    "code": "canceled",
    "message": "The analysis was canceled. You were not charged."
  },
  "progress": null,
  "usage": {
    "amount": 0,
    "currency": "usd",
    "funding": null
  },
  "metadata": null,
  "completed_at": 1793700135,
  "expires_at": null
}
```

### Descargar el informe en PDF

`GET` `https://api.fileverity.com/v1/analyses/{id}/report.pdf`

Devuelve el informe en PDF sellado de un análisis que ha terminado con éxito mientras se conserve su resultado. Las claves de prueba reciben 404. Las evidencias del documento, como las imágenes de páginas, están disponibles durante 3 horas tras el análisis; después el PDF las omite, lo que se indica con x-evidence-included: false.

#### Parámetros

| Nombre | Ubicación | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- | --- |
| `id` | ruta | cadena | Sí | ID del análisis. |
| `locale` | consulta | uno de `"en"`, `"fr"`, `"de"`, `"es"`, `"zh"`, `"vi"`, `"ar"` | No | Valor predeterminado: `"en"`. |

#### Respuestas

| Estado | Descripción | Cuerpo |
| --- | --- | --- |
| 200 | El informe en PDF. | Archivo PDF |
| 400 | Solicitud no válida. Códigos de error: invalid_parameter. | `Error` |
| 401 | Clave de API ausente o no válida. Códigos de error: missing_api_key, invalid_api_key. | `Error` |
| 404 | Recurso no encontrado. Códigos de error: not_found. | `Error` |
| 429 | Demasiadas solicitudes. Códigos de error: rate_limited. | `Error` |
| 500 | Error interno; no se cobra. Códigos de error: internal_error. | `Error` |

#### Códigos de error

| Código | Estado |
| --- | --- |
| `invalid_parameter` | 400 |
| `not_found` | 404 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Ejemplo

**Solicitud: cURL**

```bash
curl "https://api.fileverity.com/v1/analyses/an_8Hk2pQ4vN9sL1xR7cW3mY6zB/report.pdf?locale=en" \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -o Fileverity-FV-7K2M-9QXD-4T8R.pdf
```

## Modelos

### Listar modelos

`GET` `https://api.fileverity.com/v1/models`

Lista los modelos disponibles para su clave de API.

#### Respuestas

| Estado | Descripción | Cuerpo |
| --- | --- | --- |
| 200 | Los modelos disponibles. | `ModelList` |
| 401 | Clave de API ausente o no válida. Códigos de error: missing_api_key, invalid_api_key. | `Error` |
| 429 | Demasiadas solicitudes. Códigos de error: rate_limited. | `Error` |
| 500 | Error interno; no se cobra. Códigos de error: internal_error. | `Error` |

#### Respuesta 200: ModelList

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `object` | `"list"` | Sí |  |
| `data` | array de `Model` | Sí |  |

**data: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | cadena | Sí |  |
| `object` | `"model"` | Sí |  |
| `created` | entero | Sí | Marca de tiempo Unix de la versión fechada actual. |
| `owned_by` | cadena | Sí |  |
| `name` | cadena | Sí |  |
| `type` | uno de `"image"`, `"document"`, `"text"` | Sí |  |
| `description` | cadena | Sí |  |
| `snapshot` | cadena | Sí | Versión fechada a la que apunta actualmente el ID. |
| `status` | uno de `"available"`, `"preview"`, `"deprecated"` | Sí |  |
| `input` | objeto | Sí | Entrada admitida. En los archivos se indican los formatos y los límites de tamaño; en el texto, los idiomas y los límites de longitud. |
| `output` | objeto | Sí |  |
| `pricing` | objeto | Sí |  |

**input: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `formats` | array de cadenas | No |  |
| `max_bytes` | entero | No |  |
| `max_megapixels` | entero | No |  |
| `max_pages` | entero | No |  |
| `languages` | array de cadenas | No |  |
| `min_words` | entero | No |  |
| `max_characters` | entero | No |  |

**output: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `schema` | cadena | Sí | Esquema del informe en los resultados del análisis. |

**pricing: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `currency` | `"usd"` | Sí |  |
| `unit` | cadena | Sí |  |
| `unit_amount` | entero | Sí | Precio por unidad en centavos. |

#### Códigos de error

| Código | Estado |
| --- | --- |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Ejemplo

**Solicitud: cURL**

```bash
curl https://api.fileverity.com/v1/models \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"
```

**Respuesta**

```json
{
  "object": "list",
  "data": [
    {
      "id": "fvimg-2",
      "object": "model",
      "created": 1793318400,
      "owned_by": "fileverity",
      "name": "FVIMG V2",
      "type": "image",
      "description": "Image authenticity analysis. Detects AI generation and local edits, checks content credentials and metadata, and returns a verifiable report.",
      "snapshot": "fvimg-2-2026-10-30",
      "status": "available",
      "input": {
        "formats": [
          "jpeg",
          "png",
          "webp"
        ],
        "max_bytes": 10485760,
        "max_megapixels": 40
      },
      "output": {
        "schema": "fileverity.report/1"
      },
      "pricing": {
        "currency": "usd",
        "unit": "image",
        "unit_amount": 199
      }
    },
    {
      "id": "fvdoc-3",
      "object": "model",
      "created": 1793664000,
      "owned_by": "fileverity",
      "name": "FVDOC V3",
      "type": "document",
      "description": "Document fraud analysis. Evaluates AI-written text, embedded photos, edit history and signatures, and returns a verifiable report.",
      "snapshot": "fvdoc-3-2026-11-03",
      "status": "available",
      "input": {
        "formats": [
          "pdf",
          "docx",
          "doc",
          "rtf",
          "odt",
          "pptx",
          "txt"
        ],
        "max_bytes": 52428800,
        "max_pages": 100
      },
      "output": {
        "schema": "fileverity.docpro/1"
      },
      "pricing": {
        "currency": "usd",
        "unit": "document",
        "unit_amount": 599
      }
    },
    {
      "id": "fvdoc-3-text",
      "object": "model",
      "created": 1793664000,
      "owned_by": "fileverity",
      "name": "FVDOC V3 Text",
      "type": "text",
      "description": "AI-written text detection. Classifies plain text as AI-written, partly AI-written or human-written and marks the AI-written passages.",
      "snapshot": "fvdoc-3-text-2026-11-03",
      "status": "available",
      "input": {
        "languages": [
          "en",
          "fr",
          "de",
          "es",
          "zh"
        ],
        "min_words": 100,
        "max_characters": 100000
      },
      "output": {
        "schema": "fileverity.text-detection/1"
      },
      "pricing": {
        "currency": "usd",
        "unit": "1000_characters",
        "unit_amount": 14
      }
    }
  ]
}
```

### Recuperar un modelo

`GET` `https://api.fileverity.com/v1/models/{model}`

Recupera un modelo por su ID o su ID de versión fechada.

#### Parámetros

| Nombre | Ubicación | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- | --- |
| `model` | ruta | cadena | Sí | ID de modelo o ID de versión fechada. |

#### Respuestas

| Estado | Descripción | Cuerpo |
| --- | --- | --- |
| 200 | El modelo. | `Model` |
| 401 | Clave de API ausente o no válida. Códigos de error: missing_api_key, invalid_api_key. | `Error` |
| 404 | Recurso no encontrado. Códigos de error: model_not_found. | `Error` |
| 429 | Demasiadas solicitudes. Códigos de error: rate_limited. | `Error` |
| 500 | Error interno; no se cobra. Códigos de error: internal_error. | `Error` |

#### Respuesta 200: Model

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | cadena | Sí |  |
| `object` | `"model"` | Sí |  |
| `created` | entero | Sí | Marca de tiempo Unix de la versión fechada actual. |
| `owned_by` | cadena | Sí |  |
| `name` | cadena | Sí |  |
| `type` | uno de `"image"`, `"document"`, `"text"` | Sí |  |
| `description` | cadena | Sí |  |
| `snapshot` | cadena | Sí | Versión fechada a la que apunta actualmente el ID. |
| `status` | uno de `"available"`, `"preview"`, `"deprecated"` | Sí |  |
| `input` | objeto | Sí | Entrada admitida. En los archivos se indican los formatos y los límites de tamaño; en el texto, los idiomas y los límites de longitud. |
| `output` | objeto | Sí |  |
| `pricing` | objeto | Sí |  |

**input: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `formats` | array de cadenas | No |  |
| `max_bytes` | entero | No |  |
| `max_megapixels` | entero | No |  |
| `max_pages` | entero | No |  |
| `languages` | array de cadenas | No |  |
| `min_words` | entero | No |  |
| `max_characters` | entero | No |  |

**output: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `schema` | cadena | Sí | Esquema del informe en los resultados del análisis. |

**pricing: campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `currency` | `"usd"` | Sí |  |
| `unit` | cadena | Sí |  |
| `unit_amount` | entero | Sí | Precio por unidad en centavos. |

#### Códigos de error

| Código | Estado |
| --- | --- |
| `model_not_found` | 404 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Ejemplo

**Solicitud: cURL**

```bash
curl https://api.fileverity.com/v1/models/fvimg-2 \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"
```

**Respuesta**

```json
{
  "id": "fvimg-2",
  "object": "model",
  "created": 1793318400,
  "owned_by": "fileverity",
  "name": "FVIMG V2",
  "type": "image",
  "description": "Image authenticity analysis. Detects AI generation and local edits, checks content credentials and metadata, and returns a verifiable report.",
  "snapshot": "fvimg-2-2026-10-30",
  "status": "available",
  "input": {
    "formats": [
      "jpeg",
      "png",
      "webp"
    ],
    "max_bytes": 10485760,
    "max_megapixels": 40
  },
  "output": {
    "schema": "fileverity.report/1"
  },
  "pricing": {
    "currency": "usd",
    "unit": "image",
    "unit_amount": 199
  }
}
```

## Eventos de webhook

Fileverity envía estos eventos a sus endpoints de webhook. Las reglas de verificación y de entrega están en [Webhooks](https://fileverity.com/es/docs/webhooks.md).

### Evento analysis.completed

Se entrega a sus endpoints de webhook conforme a la especificación Standard Webhooks: los encabezados webhook-id, webhook-timestamp y webhook-signature (v1,<base64 HMAC-SHA256 de id.timestamp.body>, con la parte base64 de su secreto whsec_ como clave). Responda con cualquier 2xx en un plazo de 10 segundos; los fallos se reintentan con retroceso exponencial durante 3 días.

#### Cuerpo de la solicitud: application/json, obligatorio

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | cadena | Sí | También se envía como encabezado webhook-id; úselo para descartar los reintentos duplicados. |
| `object` | `"event"` | Sí |  |
| `type` | uno de `"analysis.completed"`, `"analysis.failed"`, `"balance.low"` | Sí |  |
| `created` | entero | Sí | Marca de tiempo Unix. |
| `data` | `Analysis` o `BalanceLow` | Sí | Los eventos analysis.* incluyen el mismo objeto que GET /analyses/{id}, con result siempre null; obtenga el resultado con ese endpoint. Los eventos balance.low incluyen el saldo y el umbral en centavos. |

**data (BalanceLow): campos**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `balance` | entero | Sí | Saldo en centavos. |
| `threshold` | entero | Sí | Umbral de alerta en centavos. |

### Evento analysis.failed

Se entrega a sus endpoints de webhook conforme a la especificación Standard Webhooks: los encabezados webhook-id, webhook-timestamp y webhook-signature (v1,<base64 HMAC-SHA256 de id.timestamp.body>, con la parte base64 de su secreto whsec_ como clave). Responda con cualquier 2xx en un plazo de 10 segundos; los fallos se reintentan con retroceso exponencial durante 3 días.

#### Cuerpo de la solicitud: application/json, obligatorio

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | cadena | Sí | También se envía como encabezado webhook-id; úselo para descartar los reintentos duplicados. |
| `object` | `"event"` | Sí |  |
| `type` | uno de `"analysis.completed"`, `"analysis.failed"`, `"balance.low"` | Sí |  |
| `created` | entero | Sí | Marca de tiempo Unix. |
| `data` | `Analysis` o `BalanceLow` | Sí | Los eventos analysis.* incluyen el mismo objeto que GET /analyses/{id}, con result siempre null; obtenga el resultado con ese endpoint. Los eventos balance.low incluyen el saldo y el umbral en centavos. |

### Evento balance.low

Se entrega a sus endpoints de webhook conforme a la especificación Standard Webhooks: los encabezados webhook-id, webhook-timestamp y webhook-signature (v1,<base64 HMAC-SHA256 de id.timestamp.body>, con la parte base64 de su secreto whsec_ como clave). Responda con cualquier 2xx en un plazo de 10 segundos; los fallos se reintentan con retroceso exponencial durante 3 días.

#### Cuerpo de la solicitud: application/json, obligatorio

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | cadena | Sí | También se envía como encabezado webhook-id; úselo para descartar los reintentos duplicados. |
| `object` | `"event"` | Sí |  |
| `type` | uno de `"analysis.completed"`, `"analysis.failed"`, `"balance.low"` | Sí |  |
| `created` | entero | Sí | Marca de tiempo Unix. |
| `data` | `Analysis` o `BalanceLow` | Sí | Los eventos analysis.* incluyen el mismo objeto que GET /analyses/{id}, con result siempre null; obtenga el resultado con ese endpoint. Los eventos balance.low incluyen el saldo y el umbral en centavos. |

**OpenAPI**

```bash
curl https://api.fileverity.com/v1/openapi.json
```