{ "openapi": "3.1.0", "info": { "title": "Integrations API", "version": "2026-04-22", "description": "Installation-scoped integrations API for external CMS consumers such as WordPress and Drupal plugins." }, "servers": [ { "url": "https://api.legaciti.org", "description": "Legaciti API domain" } ], "tags": [ { "name": "Integrations", "description": "Installation-authenticated integrations endpoints" } ], "components": { "securitySchemes": { "integrationApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Display-once installation credential for integrations API requests." } }, "schemas": { "IntegrationError": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "error", "code" ], "additionalProperties": false }, "InstallationSelfResponse": { "type": "object", "properties": { "installation": { "type": "object", "properties": { "id": { "type": "string" }, "workspace_id": { "type": "string" }, "platform": { "type": "string", "enum": [ "wordpress", "drupal" ] }, "status": { "type": "string", "enum": [ "draft", "pending_verification", "active", "disabled", "revoked", "archived" ] }, "display_name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "origin": { "type": "string" }, "verification_status": { "type": "string", "enum": [ "pending", "verified", "failed", "revoked" ] }, "verified_at": { "type": [ "integer", "null" ] }, "last_verification_error": { "type": [ "string", "null" ] } }, "required": [ "id", "origin", "verification_status" ] } }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "workspace_id", "platform", "status", "display_name", "created_at", "updated_at", "origins", "scopes" ] } }, "required": [ "installation" ] }, "InstallationHealthResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "version": { "type": "string", "enum": [ "2026-04-22" ] } }, "required": [ "status", "version" ] }, "InstallationPublicationsResponse": { "type": "object", "properties": { "publications": { "type": "array", "items": { "type": "object", "properties": { "doi": { "type": "string" }, "author_match_state": { "type": "string", "enum": [ "needs_attention", "complete" ] }, "title": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "doi_url": { "type": "string", "format": "uri" }, "publication_date": { "type": [ "string", "null" ] }, "publication_year": { "type": [ "integer", "null" ] }, "publication_type": { "type": [ "string", "null" ] }, "cited_by_count": { "type": [ "integer", "null" ] }, "last_fetched_at": { "type": "integer" } }, "required": [ "doi", "author_match_state", "title", "doi_url", "publication_date", "publication_year", "publication_type", "cited_by_count", "last_fetched_at" ] } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" }, "sort": { "type": "string", "enum": [ "last_fetched_at", "publication_date", "cited_by_count" ] }, "dir": { "type": "string", "enum": [ "asc", "desc" ] }, "q": { "type": "string" }, "publication_type": { "type": [ "string", "null" ] }, "publication_year": { "type": [ "integer", "null" ] }, "min_cited_by": { "type": [ "integer", "null" ] } }, "required": [ "publications", "page", "per_page", "total", "pages", "sort", "dir", "q" ] }, "InstallationWorksResponse": { "type": "object", "properties": { "works": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "work_type": { "type": [ "string", "null" ] }, "publication_date": { "type": [ "string", "null" ] }, "publication_year": { "type": [ "integer", "null" ] }, "created_at": { "type": "integer" }, "href": { "type": "string", "format": "uri" } }, "required": [ "id", "title", "work_type", "publication_date", "publication_year", "created_at", "href" ] } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" }, "sort": { "type": "string", "enum": [ "created_at", "publication_date", "publication_year" ] }, "dir": { "type": "string", "enum": [ "asc", "desc" ] }, "q": { "type": "string" }, "work_type": { "type": [ "string", "null" ] }, "publication_year": { "type": [ "integer", "null" ] } }, "required": [ "works", "page", "per_page", "total", "pages", "sort", "dir", "q" ] }, "InstallationProjectsResponse": { "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "programme": { "type": "string" }, "title": { "type": "string" }, "abstract": { "type": [ "string", "null" ] }, "start_date": { "type": [ "string", "null" ] }, "end_date": { "type": [ "string", "null" ] }, "cesam_funding_amount": { "type": [ "number", "null" ] }, "cesam_funding_currency": { "type": "string", "enum": [ "EUR", "USD" ] }, "total_funding_amount": { "type": [ "number", "null" ] }, "total_funding_currency": { "type": "string", "enum": [ "EUR", "USD" ] }, "funding_entities": { "type": "array", "items": {} }, "proponent_institution": { "type": [ "string", "null" ] }, "project_logo": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "funding_partner_images": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "created_at": { "type": "integer" }, "href": { "type": "string", "format": "uri" } }, "required": [ "id", "programme", "title", "abstract", "start_date", "end_date", "cesam_funding_amount", "cesam_funding_currency", "total_funding_amount", "total_funding_currency", "funding_entities", "proponent_institution", "project_logo", "funding_partner_images", "created_at", "href" ] } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" }, "sort": { "type": "string", "enum": [ "created_at", "start_date", "end_date" ] }, "dir": { "type": "string", "enum": [ "asc", "desc" ] }, "q": { "type": "string" }, "funding_currency": { "type": [ "string", "null" ], "enum": [ "EUR", "USD", null ] } }, "required": [ "projects", "page", "per_page", "total", "pages", "sort", "dir", "q" ] }, "InstallationPeopleResponse": { "type": "object", "properties": { "people": { "type": "array", "items": { "type": "object", "properties": { "name": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "photo_url": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "people_type": { "type": [ "string", "null" ] } }, "required": [ "name", "photo_url", "slug", "people_type" ] } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" }, "q": { "type": "string" } }, "required": [ "people", "page", "per_page", "total", "pages", "q" ] } } }, "paths": { "/integrations/v1/health": { "get": { "summary": "Integrations API health check", "tags": [ "Integrations" ], "security": [], "responses": { "200": { "description": "Worker health response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "version": { "type": "string", "enum": [ "2026-04-22" ] } }, "required": [ "status", "version" ] } } } } } } }, "/integrations/v1/installation": { "get": { "summary": "Resolve current installation", "tags": [ "Integrations" ], "security": [ { "integrationApiKey": [] } ], "responses": { "200": { "description": "Current installation context.", "content": { "application/json": { "schema": { "type": "object", "properties": { "installation": { "type": "object", "properties": { "id": { "type": "string" }, "workspace_id": { "type": "string" }, "platform": { "type": "string", "enum": [ "wordpress", "drupal" ] }, "status": { "type": "string", "enum": [ "draft", "pending_verification", "active", "disabled", "revoked", "archived" ] }, "display_name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "origin": { "type": "string" }, "verification_status": { "type": "string", "enum": [ "pending", "verified", "failed", "revoked" ] }, "verified_at": { "type": [ "integer", "null" ] }, "last_verification_error": { "type": [ "string", "null" ] } }, "required": [ "id", "origin", "verification_status" ] } }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "workspace_id", "platform", "status", "display_name", "created_at", "updated_at", "origins", "scopes" ] } }, "required": [ "installation" ] } } } }, "401": { "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "error", "code" ], "additionalProperties": false } } } }, "403": { "description": "Credential inactive, expired, or origin rejected.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "error", "code" ], "additionalProperties": false } } } } } } }, "/integrations/v1/publications": { "get": { "summary": "List publications for integrations consumers", "description": "Read-only publication listing for installation-authenticated consumers with the publications.read scope.", "tags": [ "Integrations" ], "security": [ { "integrationApiKey": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "last_fetched_at", "publication_date", "cited_by_count" ], "default": "last_fetched_at" } }, { "name": "dir", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "publication_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "publication_year", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "min_cited_by", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Filtered publications visible to the integrations consumer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "publications": { "type": "array", "items": { "type": "object", "properties": { "doi": { "type": "string" }, "author_match_state": { "type": "string", "enum": [ "needs_attention", "complete" ] }, "title": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "doi_url": { "type": "string", "format": "uri" }, "publication_date": { "type": [ "string", "null" ] }, "publication_year": { "type": [ "integer", "null" ] }, "publication_type": { "type": [ "string", "null" ] }, "cited_by_count": { "type": [ "integer", "null" ] }, "last_fetched_at": { "type": "integer" } }, "required": [ "doi", "author_match_state", "title", "doi_url", "publication_date", "publication_year", "publication_type", "cited_by_count", "last_fetched_at" ] } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" }, "sort": { "type": "string", "enum": [ "last_fetched_at", "publication_date", "cited_by_count" ] }, "dir": { "type": "string", "enum": [ "asc", "desc" ] }, "q": { "type": "string" }, "publication_type": { "type": [ "string", "null" ] }, "publication_year": { "type": [ "integer", "null" ] }, "min_cited_by": { "type": [ "integer", "null" ] } }, "required": [ "publications", "page", "per_page", "total", "pages", "sort", "dir", "q" ] } } } }, "400": { "description": "Invalid query parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "error", "code" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "error", "code" ], "additionalProperties": false } } } }, "403": { "description": "Credential inactive, origin rejected, or required scope not granted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "error", "code" ], "additionalProperties": false } } } } } } }, "/integrations/v1/works": { "get": { "summary": "List works for integrations consumers", "description": "Read-only works listing for installation-authenticated consumers with the works.read scope.", "tags": [ "Integrations" ], "security": [ { "integrationApiKey": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "publication_date", "publication_year" ], "default": "created_at" } }, { "name": "dir", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "work_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "publication_year", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Filtered works visible to the integrations consumer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "works": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "work_type": { "type": [ "string", "null" ] }, "publication_date": { "type": [ "string", "null" ] }, "publication_year": { "type": [ "integer", "null" ] }, "created_at": { "type": "integer" }, "href": { "type": "string", "format": "uri" } }, "required": [ "id", "title", "work_type", "publication_date", "publication_year", "created_at", "href" ] } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" }, "sort": { "type": "string", "enum": [ "created_at", "publication_date", "publication_year" ] }, "dir": { "type": "string", "enum": [ "asc", "desc" ] }, "q": { "type": "string" }, "work_type": { "type": [ "string", "null" ] }, "publication_year": { "type": [ "integer", "null" ] } }, "required": [ "works", "page", "per_page", "total", "pages", "sort", "dir", "q" ] } } } }, "400": { "description": "Invalid query parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "error", "code" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "error", "code" ], "additionalProperties": false } } } }, "403": { "description": "Credential inactive, origin rejected, or required scope not granted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "error", "code" ], "additionalProperties": false } } } } } } }, "/integrations/v1/projects": { "get": { "summary": "List projects for integrations consumers", "description": "Read-only project listing for installation-authenticated consumers with the projects.read scope.", "tags": [ "Integrations" ], "security": [ { "integrationApiKey": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "start_date", "end_date" ], "default": "created_at" } }, { "name": "dir", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "funding_currency", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "EUR", "USD" ] } } ], "responses": { "200": { "description": "Filtered projects visible to the integrations consumer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "programme": { "type": "string" }, "title": { "type": "string" }, "abstract": { "type": [ "string", "null" ] }, "start_date": { "type": [ "string", "null" ] }, "end_date": { "type": [ "string", "null" ] }, "cesam_funding_amount": { "type": [ "number", "null" ] }, "cesam_funding_currency": { "type": "string", "enum": [ "EUR", "USD" ] }, "total_funding_amount": { "type": [ "number", "null" ] }, "total_funding_currency": { "type": "string", "enum": [ "EUR", "USD" ] }, "funding_entities": { "type": "array", "items": {} }, "proponent_institution": { "type": [ "string", "null" ] }, "project_logo": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "funding_partner_images": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "created_at": { "type": "integer" }, "href": { "type": "string", "format": "uri" } }, "required": [ "id", "programme", "title", "abstract", "start_date", "end_date", "cesam_funding_amount", "cesam_funding_currency", "total_funding_amount", "total_funding_currency", "funding_entities", "proponent_institution", "project_logo", "funding_partner_images", "created_at", "href" ] } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" }, "sort": { "type": "string", "enum": [ "created_at", "start_date", "end_date" ] }, "dir": { "type": "string", "enum": [ "asc", "desc" ] }, "q": { "type": "string" }, "funding_currency": { "type": [ "string", "null" ], "enum": [ "EUR", "USD", null ] } }, "required": [ "projects", "page", "per_page", "total", "pages", "sort", "dir", "q" ] } } } }, "400": { "description": "Invalid query parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "error", "code" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "error", "code" ], "additionalProperties": false } } } }, "403": { "description": "Credential inactive, origin rejected, or required scope not granted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "error", "code" ], "additionalProperties": false } } } } } } }, "/integrations/v1/people": { "get": { "summary": "List people for integrations consumers", "description": "Read-only people listing for installation-authenticated consumers with the people.read scope.", "tags": [ "Integrations" ], "security": [ { "integrationApiKey": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Filtered people visible to the integrations consumer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "people": { "type": "array", "items": { "type": "object", "properties": { "name": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "photo_url": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "people_type": { "type": [ "string", "null" ] } }, "required": [ "name", "photo_url", "slug", "people_type" ] } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" }, "q": { "type": "string" } }, "required": [ "people", "page", "per_page", "total", "pages", "q" ] } } } }, "400": { "description": "Invalid query parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "error", "code" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "error", "code" ], "additionalProperties": false } } } }, "403": { "description": "Credential inactive, origin rejected, or required scope not granted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "error", "code" ], "additionalProperties": false } } } } } } }, "/integrations/v1/verify/{originId}": { "get": { "summary": "Read verification token for one origin", "description": "Plain-text verification endpoint that origin owners mirror from their own site during manual challenge verification.", "tags": [ "Integrations" ], "security": [], "parameters": [ { "name": "originId", "in": "path", "required": true, "description": "Stable integration origin identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification token in plain text.", "content": { "text/plain": { "schema": { "type": "string", "description": "Plain-text verification token served from the origin-specific proof endpoint." } } } }, "400": { "description": "Missing or malformed origin identifier.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Origin not found or no verification token available.", "content": { "text/plain": { "schema": { "type": "string" } } } } } } } } }