API & Agent Documentation

Plenum is agent-ready. Every tenant is reachable through a public REST API, a Model Context Protocol (MCP) server, and OAuth 2.1 client credentials. Use this index to discover endpoints, authentication, scopes, and rate limits.

Discovery

• OpenAPI 3.1: /api/public/openapi.json
• API Catalog (RFC 9727): /.well-known/api-catalog
• MCP Server Card (platform): /.well-known/mcp.json
• MCP Server Card (per tenant): /.well-known/mcp.json/{slug}
• OAuth 2.1 Authorization Server (RFC 8414): /.well-known/oauth-authorization-server
• OAuth Protected Resource (RFC 9728): /.well-known/oauth-protected-resource

MCP Server

Endpoint pattern: POST https://app.plenum.pro/mcp/{slug}. JSON-RPC 2.0 runs over HTTP with protocol version 2025-06-18.

Anonymous read tools: list_services, list_brands, check_service_area, get_pricer_templates, calculate_pricing, get_business_hours, check_rebate_eligibility.

Write tools require OAuth 2.1 bearer tokens:

• submit_lead: scope leads:write. Replaces reCAPTCHA for authenticated agents. Tokens are pinned to a single tenant (companyId); cross-tenant calls return 403.

OAuth 2.1 (client_credentials)

Supported grants: authorization_code (PKCE, user-delegated) and client_credentials (machine-to-machine). Tokens are opaque, hashed at rest, bound to a single tenant, and rotate on refresh.

Supported scopes: leads:write, rebates:read, pricing:read, company:read.

Contact [email protected] to register an API client.

Rate Limits

• Anonymous MCP: 30 requests / 10 min per IP per tenant.
• OAuth-authenticated MCP: 300 requests / 10 min per client per tenant.
• Retry-After, X-RateLimit-Limit, and X-RateLimit-Remaining are emitted on 429s.

Content Signals

Marketing surfaces emit the Content-Signal directive from /robots.txt per the IETF draft-romm-aipref-contentsignals spec. Portal and app-side hosts disallow all crawling.

Questions

Email [email protected]. Bug reports welcome.