Affinda Tags API
Tag management for parsed documents. Tags can be arbitrarily attached to documents to support routing, segmentation, search filters, and downstream workflow triggers. Supports batch-add and batch-remove on document collections.
OpenAPI Specification
openapi: 3.0.3
info:
title: Affinda Annotations Add x-hidden to endpoints Tags 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: Tags
paths:
/v3/tags:
get:
tags:
- Tags
summary: Get list of all tags
operationId: getAllTags
description: Returns your tags.
parameters:
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/offsetParam'
- in: query
name: workspace
schema:
$ref: '#/components/schemas/identifier'
description: Filter by workspace.
- in: query
name: name
schema:
$ref: '#/components/schemas/name'
description: Filter by name.
responses:
'200':
description: All matching tags.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Tag'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
default:
$ref: '#/components/responses/DefaultError'
post:
tags:
- Tags
summary: Create a tag
operationId: createTag
description: Create a tag
responses:
'201':
description: Successfully created a tag.
content:
application/json:
schema:
$ref: '#/components/schemas/Tag'
'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/TagCreate'
/v3/tags/{id}:
get:
tags:
- Tags
summary: Get specific tag
operationId: getTag
description: Return a specific tag.
parameters:
- in: path
required: true
name: id
description: Tag's ID
schema:
$ref: '#/components/schemas/id'
responses:
'200':
description: Successfully retrieved tag.
content:
application/json:
schema:
$ref: '#/components/schemas/Tag'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
default:
$ref: '#/components/responses/DefaultError'
patch:
tags:
- Tags
summary: Update a tag
operationId: updateTag
description: Update data of an tag.
parameters:
- in: path
required: true
name: id
description: Tag's ID
schema:
$ref: '#/components/schemas/id'
requestBody:
description: Tag data to update
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TagUpdate'
responses:
'200':
description: Successfully updated tag data.
content:
application/json:
schema:
$ref: '#/components/schemas/Tag'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
default:
$ref: '#/components/responses/DefaultError'
delete:
tags:
- Tags
summary: Delete an tag
operationId: deleteTag
description: Deletes the specified tag from the database.
parameters:
- in: path
required: true
name: id
description: Tag's ID
schema:
$ref: '#/components/schemas/id'
responses:
'204':
$ref: '#/components/responses/204NoContent'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
default:
$ref: '#/components/responses/DefaultError'
/v3/documents/batch_add_tag:
post:
tags:
- Tags
summary: Add a tag to documents
operationId: batchAddTag
description: 'Add a tag to documents.
Tags are used to group documents together.
Tags can be used to filter documents.
'
requestBody:
description: Specify the tag and the documents to tag
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BatchAddTagRequest'
responses:
'204':
description: Document successfully tagged
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
default:
$ref: '#/components/responses/DefaultError'
/v3/documents/batch_remove_tag:
post:
tags:
- Tags
summary: Remove a tag from documents
operationId: batchRemoveTag
description: Remove a tag from documents.
requestBody:
description: Specify the tag and the documents to remove the tag from
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BatchRemoveTagRequest'
responses:
'204':
description: Document successfully tagged
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
default:
$ref: '#/components/responses/DefaultError'
components:
schemas:
id:
type: integer
description: Uniquely identify a tag.
example: 1
minimum: 1
TagUpdate:
type: object
properties:
name:
$ref: '#/components/schemas/name'
workspace:
$ref: '#/components/schemas/identifier'
TagCreate:
type: object
required:
- name
- workspace
properties:
name:
$ref: '#/components/schemas/name'
workspace:
$ref: '#/components/schemas/identifier'
Tag:
type: object
required:
- id
- name
- workspace
- documentCount
properties:
id:
type: integer
description: Uniquely identify a tag.
example: 1
minimum: 1
name:
type: string
workspace:
$ref: '#/components/schemas/identifier'
documentCount:
type: integer
minimum: 0
description: Number of documents tagged with this.
BatchAddTagRequest:
type: object
properties:
identifiers:
type: array
items:
$ref: '#/components/schemas/DocumentMeta_properties-identifier'
description: List of documents to tag
tag:
type: integer
example: 1
description: The tag's ID
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
BatchRemoveTagRequest:
type: object
properties:
identifiers:
type: array
items:
$ref: '#/components/schemas/DocumentMeta_properties-identifier'
description: List of documents to remove tag from
tag:
type: integer
description: The tag's ID
identifier:
type: string
description: Uniquely identify a workspace.
example: mEFayXdO
name:
type: string
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).'