Track the status and findings of validation rules attached to parsed documents. Validation results record passes, failures, and remediation context for field-level rules and inform the embeddable validation UI. Supports batch create and delete.
openapi: 3.0.3
info:
title: Affinda Annotations Add x-hidden to endpoints Validation Results API
version: 3.0.0
description: Affinda Annotations API — subset of the Affinda v3 Document Processing API.
servers:
- url: https://{region}.affinda.com
description: 'Select the correct server for your instance: api (AUS/Global), api.us1 (US), or api.eu1 (EU).'
variables:
region:
default: api
description: The instance region. Use 'api' for AUS/Global, 'api.us1' for US, or 'api.eu1' for EU. You can find your region in the Affinda web app URL.
enum:
- api
- api.eu1
- api.us1
x-ms-parameter-location: client
security:
- ApiKeyAuth: []
tags:
- name: Validation Results
description: 'Operations to manage validation results.
Validation results track the status and outcomes of document validation processes.
'
paths:
/v3/validation_results:
get:
tags:
- Validation Results
summary: Get list of all validation results
operationId: getAllValidationResults
description: Returns the validation results of a document.
parameters:
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/limitParam'
- in: query
name: document
required: true
schema:
$ref: '#/components/schemas/DocumentMeta_properties-identifier'
description: Filter by document.
responses:
'200':
description: All matching workspace memberships.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ValidationResult'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
default:
$ref: '#/components/responses/DefaultError'
post:
tags:
- Validation Results
summary: Create a validation result
operationId: createValidationResult
description: Create a validation result.
responses:
'201':
description: Successfully created a validation result.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationResult'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
default:
$ref: '#/components/responses/DefaultError'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationResultCreate'
/v3/validation_results/{id}:
get:
tags:
- Validation Results
summary: Get specific validation result
operationId: getValidationResult
description: Return a specific validation result.
parameters:
- in: path
required: true
name: id
description: Validation result's ID.
schema:
$ref: '#/components/schemas/ValidationResult_properties-id'
responses:
'200':
description: Successfully retrieved validation result.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationResult'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
default:
$ref: '#/components/responses/DefaultError'
patch:
tags:
- Validation Results
summary: Update a validation result
operationId: updateValidationResult
description: Update a validation result.
parameters:
- in: path
required: true
name: id
description: Validation result's ID.
schema:
$ref: '#/components/schemas/ValidationResult_properties-id'
requestBody:
description: Validation result data to update
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationResultUpdate'
responses:
'200':
description: Successfully updated validation result.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationResult'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
default:
$ref: '#/components/responses/DefaultError'
delete:
tags:
- Validation Results
summary: Delete a validation result
operationId: deleteValidationResult
description: Remove validation result.
parameters:
- in: path
required: true
name: id
description: Validation result's ID.
schema:
$ref: '#/components/schemas/ValidationResult_properties-id'
responses:
'204':
$ref: '#/components/responses/204NoContent'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
default:
$ref: '#/components/responses/DefaultError'
/v3/validation_results/batch_create:
post:
tags:
- Validation Results
summary: Batch create validation results
operationId: batchCreateValidationResults
description: Batch create validation results.
responses:
'201':
description: Successfully created validation results.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ValidationResult'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
default:
$ref: '#/components/responses/DefaultError'
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ValidationResultCreate'
/v3/validation_results/batch_delete:
post:
tags:
- Validation Results
summary: Batch delete validation results
operationId: batchDeleteValidationResults
description: Batch delete validation results
responses:
'204':
$ref: '#/components/responses/204NoContent'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
default:
$ref: '#/components/responses/DefaultError'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BatchDeleteValidationResultsRequest'
components:
schemas:
ValidationResult_properties-id:
type: integer
description: Validation Result's ID
example: 1
minimum: 1
ValidationResultCreate:
type: object
required:
- annotations
- ruleSlug
- message
- document
properties:
annotations:
$ref: '#/components/schemas/annotations'
passed:
$ref: '#/components/schemas/passed'
ruleSlug:
$ref: '#/components/schemas/ruleSlug'
message:
$ref: '#/components/schemas/message'
document:
$ref: '#/components/schemas/DocumentMeta_properties-identifier'
ValidationResult:
type: object
additionalProperties: false
nullable: false
description: Validation result arising from a ValidationRule
required:
- id
- annotations
- passed
- ruleSlug
- message
- document
properties:
id:
type: integer
description: Validation Result's ID
example: 1
minimum: 1
annotations:
type: array
items:
type: integer
description: List of annotation ids that were validated
nullable: false
example:
- 1
- 2
- 3
passed:
type: boolean
description: Whether the validation passed or not, null if the validation was not applicable
example: true
nullable: true
ruleSlug:
type: string
description: The kebab-case slug of the validation rule that was applied
example: supplier-name-is-alphanumeric
pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
message:
type: string
description: Message explaining why the validation failed
example: Expected 'ThisInputShouldMatch' to match regex pattern '[0-9]*
document:
$ref: '#/components/schemas/DocumentMeta_properties-identifier'
message:
type: string
description: Message explaining why the validation failed
example: Expected 'ThisInputShouldMatch' to match regex pattern '[0-9]*
passed:
type: boolean
description: Whether the validation passed or not, null if the validation was not applicable
example: true
nullable: true
ruleSlug:
type: string
description: The kebab-case slug of the validation rule that was applied
example: supplier-name-is-alphanumeric
pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
BatchDeleteValidationResultsRequest:
type: object
additionalProperties: false
required:
- ids
properties:
ids:
type: array
items:
type: integer
description: List of validation result IDs to delete.
example:
- 123
- 124
- 125
ValidationResultUpdate:
type: object
properties:
annotations:
$ref: '#/components/schemas/annotations'
passed:
$ref: '#/components/schemas/passed'
ruleSlug:
$ref: '#/components/schemas/ruleSlug'
message:
$ref: '#/components/schemas/message'
document:
$ref: '#/components/schemas/DocumentMeta_properties-identifier'
RequestError:
type: object
additionalProperties: false
required:
- type
- errors
properties:
type:
type: string
example: validation_error
errors:
type: array
items:
type: object
required:
- attr
- code
- detail
properties:
attr:
type: string
nullable: true
example: non_field_errors
code:
type: string
example: unique
detail:
type: string
example: This index name has already been used
DocumentMeta_properties-identifier:
type: string
description: Unique identifier for the document
annotations:
type: array
items:
type: integer
description: List of annotation ids that were validated
nullable: false
example:
- 1
- 2
- 3
parameters:
limitParam:
in: query
name: limit
required: false
schema:
type: integer
minimum: 1
maximum: 100
example: 20
description: The numbers of results to return.
x-ms-parameter-location: method
offsetParam:
in: query
name: offset
required: false
schema:
type: integer
minimum: 0
example: 0
description: The number of documents to skip before starting to collect the result set.
x-ms-parameter-location: method
responses:
401Error:
description: Authorisation error
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
x-ms-error-response: true
DefaultError:
description: UnexpectedError
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
x-ms-error-response: true
400Error:
description: Bad request. If it is a validation error will contain a list of each invalid field
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
x-ms-error-response: true
204NoContent:
description: Delete successful, no content returned
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
description: 'Basic authentication using an API key, e.g. `{Authorization: Bearer aff_0bb4fbdf97b7e4111ff6c0015471094155f91}`.
You can find your API key within the Settings page of the [Affinda web app](https://app.affinda.com/). You can obtain an API key by [signing up for a free trial](https://app.affinda.com/auth/register).'