Public-safe API guidance for teams integrating researchMTR into production workflows
This page explains how to think about the platform API surface publicly: what it is for, where authentication belongs, how to separate internal-only operations from safe integration layers, and how to design implementation around stable workflow outcomes.
Focus on outcome-oriented integrations
Authentication boundary
Keep private tokens, admin configuration, and internal controls out of public docs. Public docs should explain where auth is required and how clients should manage it safely.
Workflow entry points
Describe the business workflow being triggered, such as analysis, generation, or publishing support, rather than dumping raw route lists without context.
Machine-readable discovery
Expose clean OpenAPI surfaces for approved integrations so AI agents and partner systems can understand safe operations and expected payload shapes.
Error handling expectations
Document timeouts, validation rules, and callback retries so integrations are resilient and operationally predictable.
- Define the workflow to expose publicly.
- Separate internal-only endpoints from partner-safe operations.
- Publish a machine-readable schema for approved entry points.
- Connect callbacks or webhooks only where downstream systems need completion updates.
OpenAPI
Use a curated schema for approved public operations and reference it from discovery files when it is ready for external consumption. This project now exposes JSON and YAML variants, while llms-full.txt adds live blog-level discovery context when the WordPress feed is reachable.
Versioning
Treat externally consumed payload contracts as stable interfaces. Avoid undocumented breaking changes in callback data or request bodies.
Governance
Pair public docs with internal review so SEO-facing documentation stays accurate, safe, and aligned with the real production workflow. AI-agent metadata is published at ai-plugin.json.