{"openapi": "3.0.1", "info": {"title": "Annif REST API", "version": "v1"}, "servers": [{"url": "/v1"}], "paths": {"/": {"get": {"tags": ["API information"], "summary": "get basic information about the API service", "operationId": "annif.rest.show_info", "responses": {"200": {"description": "successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiInfo"}}}}}}}, "/vocabs": {"get": {"tags": ["Vocabulary information"], "summary": "get a list of vocabularies", "operationId": "annif.rest.list_vocabs", "responses": {"200": {"description": "successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/VocabularyList"}}}}}}}, "/projects": {"get": {"tags": ["Project administration"], "summary": "get a list of projects", "operationId": "annif.rest.list_projects", "responses": {"200": {"description": "successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProjectList"}}}}}}}, "/projects/{project_id}": {"get": {"tags": ["Project administration"], "summary": "show project information", "operationId": "annif.rest.show_project", "parameters": [{"$ref": "#/components/parameters/project_id"}], "responses": {"200": {"description": "successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Project"}}}}, "404": {"$ref": "#/components/responses/NotFound"}}}}, "/projects/{project_id}/suggest": {"post": {"tags": ["Automatic subject indexing"], "summary": "suggest subjects for a given text", "description": "This method suggests relevant subjects for a given input text (with optional metadata). It supports optional parameters to control the number of results, score threshold, and language of the subject labels.\n", "operationId": "annif.rest.suggest", "parameters": [{"$ref": "#/components/parameters/project_id"}], "requestBody": {"content": {"application/x-www-form-urlencoded": {"schema": {"type": "object", "required": ["text"], "properties": {"text": {"type": "string", "description": "input text"}, "limit": {"type": "integer", "description": "maximum number of results to return", "format": "int32", "default": 10, "minimum": 0}, "threshold": {"type": "number", "description": "minimum score threshold, below which results will not be returned", "default": 0.0, "minimum": 0.0, "maximum": 1.0}, "language": {"type": "string", "description": "language of subject labels"}}, "additionalProperties": {"type": "string", "description": "Additional metadata properties, starting with 'metadata_'"}}}}, "required": true}, "responses": {"200": {"description": "successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SuggestionResultList"}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "404": {"$ref": "#/components/responses/NotFound"}, "503": {"$ref": "#/components/responses/ServiceUnavailable"}}}}, "/projects/{project_id}/suggest-batch": {"post": {"tags": ["Automatic subject indexing"], "summary": "suggest subjects for the given batch of up to 32 documents", "description": "This method suggests relevant subjects for a batch of up to 32 input texts (with optional metadata). It supports optional parameters to control the number of results, score threshold, and language of the subject labels.\n", "operationId": "annif.rest.suggest_batch", "parameters": [{"$ref": "#/components/parameters/project_id"}, {"in": "query", "name": "limit", "schema": {"type": "integer", "format": "int32", "default": 10, "minimum": 0}, "description": "maximum number of results to return"}, {"in": "query", "name": "threshold", "schema": {"type": "number", "default": 0.0, "minimum": 0.0, "maximum": 1.0}, "description": "minimum score threshold, below which results will not be returned"}, {"in": "query", "name": "language", "schema": {"type": "string"}, "description": "language of subject labels"}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["documents"], "properties": {"documents": {"type": "array", "maxItems": 32, "items": {"$ref": "#/components/schemas/Document"}}}}}}, "required": true}, "responses": {"200": {"description": "successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BatchSuggestionResultList"}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "404": {"$ref": "#/components/responses/NotFound"}, "503": {"$ref": "#/components/responses/ServiceUnavailable"}}, "x-codegen-request-body-name": "documents"}}, "/projects/{project_id}/learn": {"post": {"tags": ["Learning from feedback"], "summary": "learn from manually indexed documents", "operationId": "annif.rest.learn", "parameters": [{"$ref": "#/components/parameters/project_id"}], "requestBody": {"description": "documents to learn from", "content": {"application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/IndexedDocument"}}}}, "required": true}, "responses": {"204": {"description": "successful operation", "content": {"application/json": {}}}, "403": {"$ref": "#/components/responses/NotAllowed"}, "404": {"$ref": "#/components/responses/NotFound"}, "503": {"$ref": "#/components/responses/ServiceUnavailable"}}, "x-codegen-request-body-name": "documents"}}, "/detect-language": {"post": {"tags": ["Language detection"], "summary": "detect the language of a text given a list of candidate languages", "operationId": "annif.rest.detect_language", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["text", "languages"], "properties": {"text": {"type": "string", "description": "input text", "example": "A quick brown fox jumped over the lazy dog."}, "languages": {"type": "array", "description": "candidate languages as IETF BCP 47 codes", "items": {"type": "string", "maxLength": 3, "minLength": 2, "example": "en"}, "minItems": 1, "maxItems": 5}}}}}, "required": true}, "responses": {"200": {"description": "successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DetectedLanguages"}}}}, "400": {"description": "Bad Request", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}}}}}, "components": {"schemas": {"ApiInfo": {"required": ["title", "version"], "type": "object", "properties": {"title": {"type": "string", "example": "Annif REST API"}, "version": {"type": "string", "example": "0.60.0"}}, "description": "REST API information"}, "ProjectBackend": {"required": ["backend_id"], "type": "object", "properties": {"backend_id": {"type": "string", "example": "my-backend"}}, "description": "A backend of a project"}, "Vocabulary": {"required": ["vocab_id"], "type": "object", "properties": {"vocab_id": {"type": "string", "example": "yso"}, "languages": {"type": "array", "items": {"type": "string", "example": "en"}}, "size": {"type": "integer", "example": 1000, "nullable": true}, "loaded": {"type": "boolean", "example": true}}, "description": "A subject vocabulary"}, "VocabularyList": {"type": "object", "properties": {"vocabs": {"type": "array", "items": {"$ref": "#/components/schemas/Vocabulary"}}}, "description": "A list of subject vocabularies"}, "Project": {"required": ["backend", "language", "name", "project_id"], "type": "object", "properties": {"project_id": {"type": "string", "example": "my-project"}, "name": {"type": "string", "example": "My Project"}, "language": {"type": "string", "example": "en"}, "backend": {"$ref": "#/components/schemas/ProjectBackend"}, "vocab": {"$ref": "#/components/schemas/Vocabulary", "nullable": true}, "vocab_language": {"type": "string", "example": "en", "nullable": true}, "is_trained": {"type": "boolean", "example": true, "nullable": true}, "modification_time": {"type": "string", "format": "date-time", "example": "2020-05-19T16:42:42+00:00", "nullable": true}}, "description": "A project definition"}, "ProjectList": {"type": "object", "properties": {"projects": {"type": "array", "items": {"$ref": "#/components/schemas/Project"}}}, "description": "A list of projects"}, "SuggestionResult": {"required": ["label", "score", "uri"], "type": "object", "properties": {"uri": {"type": "string", "example": "http://example.org/subject1"}, "label": {"type": "string", "example": "Archaeology"}, "notation": {"type": "string", "example": "42.42", "nullable": true}, "score": {"type": "number", "example": 0.85}}, "description": "A single candidate subject for a document"}, "SuggestionResultList": {"type": "object", "properties": {"results": {"type": "array", "items": {"$ref": "#/components/schemas/SuggestionResult"}}}, "description": "A list of analysis results"}, "BatchSuggestionResultList": {"type": "array", "items": {"allOf": [{"$ref": "#/components/schemas/SuggestionResultList"}, {"type": "object", "properties": {"document_id": {"type": "string", "example": "doc-1234", "nullable": true}}}]}, "description": "A list of batch analysis results"}, "Document": {"type": "object", "required": ["text"], "properties": {"text": {"type": "string", "example": "A quick brown fox jumped over the lazy dog."}, "document_id": {"type": "string", "example": "doc-1234"}, "metadata": {"type": "object", "additionalProperties": {"type": "string"}}}, "description": "A document with an optional identifier and/or metadata"}, "IndexedDocument": {"type": "object", "properties": {"text": {"type": "string", "example": "A quick brown fox jumped over the lazy dog."}, "metadata": {"type": "object", "additionalProperties": {"type": "string"}}, "subjects": {"type": "array", "items": {"type": "object", "required": ["uri"], "properties": {"uri": {"type": "string", "example": "http://example.org/subject1"}, "label": {"type": "string", "example": "Vulpes vulpes"}}}}}, "description": "A document with attached, known good subjects"}, "DetectedLanguages": {"type": "object", "properties": {"results": {"type": "array", "items": {"type": "object", "properties": {"language": {"type": "string", "example": "en", "nullable": true}, "score": {"type": "number", "example": 0.85}}}}}, "description": "Candidate languages with their associated scores"}, "Problem": {"type": "object", "properties": {"type": {"type": "string", "description": "An absolute URI that identifies the problem type.  When dereferenced,\nit SHOULD provide human-readable documentation for the problem type\n(e.g., using HTML).\n", "format": "uri", "example": "https://zalando.github.io/problem/constraint-violation", "default": "about:blank"}, "title": {"type": "string", "description": "A short, summary of the problem type. Written in english and readable\nfor engineers (usually not suited for non technical stakeholders and\nnot localized); example: Service Unavailable\n"}, "status": {"maximum": 600, "exclusiveMaximum": true, "minimum": 100, "type": "integer", "description": "The HTTP status code generated by the origin server for this occurrence\nof the problem.\n", "format": "int32", "example": 503}, "detail": {"type": "string", "description": "A human readable explanation specific to this occurrence of the\nproblem.\n", "example": "Connection to database timed out"}, "instance": {"type": "string", "description": "An absolute URI that identifies the specific occurrence of the problem.\nIt may or may not yield further information if dereferenced.\n", "format": "uri"}}}}, "parameters": {"project_id": {"name": "project_id", "in": "path", "description": "project identifier", "required": true, "schema": {"type": "string"}, "example": "dummy-fi"}}, "responses": {"BadRequest": {"description": "Bad Request", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}, "NotFound": {"description": "Project not found", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}, "NotAllowed": {"description": "Operation is not allowed", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}, "ServiceUnavailable": {"description": "Service Unavailable", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}}}}