AI Promo Services API & MCP | Reports and Subscriptions

Start with a real request

Open the capability example above to receive a complete JSON record. It includes its stable ID, description, availability limitations, documentation link and verification state.

curl 'https://aipromoservices.com/v1/capabilities/developer-interface'

Lists return data, pagination.nextCursor and meta. Set limit from 1 to 100 (default 25). Pass the returned cursor unchanged to read the next page; a null cursor means the list is complete.

curl 'https://aipromoservices.com/v1/integrations?limit=5'
# For the next page, add &cursor= followed by pagination.nextCursor.

Capabilities: first five records and /v1/capabilities/{id}
Integration requirements and status
Methodology inputs, outputs and limitations
Prospective pricing and trial terms

These resources support GET and HEAD. No tokens, cookies, property IDs or account identifiers belong in the request.

Connect an assistant with MCP

Use https://aipromoservices.com/mcp as the Streamable HTTP endpoint. It returns JSON responses and does not offer an SSE stream or server-initiated messages. Supported protocol versions are 2025-11-25 and 2025-06-18. No session ID is required.

Initialize first. Include both JSON and SSE in Accept, as the MCP transport requires:

curl 'https://aipromoservices.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"public-docs-example","version":"1.0"}}}'

Use the returned protocol version in MCP-Protocol-Version for subsequent requests. Send the initialized notification (HTTP 202 with an empty body):

curl 'https://aipromoservices.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","method":"notifications/initialized"}'

Then call a tool. This example reads the boundary methodology:

curl 'https://aipromoservices.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_methodology","arguments":{"id":"public-developer-surface"}}}'

The full record appears in result.structuredContent.methodology and in the text content. To discover input schemas, send {"jsonrpc":"2.0","id":3,"method":"tools/list"} with the same headers.

search_docs: search public documentation with {"query":"publishing","limit":5}. Returns results with usable documentation links.
get_product_capabilities: read {"id":"developer-interface"}, or list with {"limit":5} and the returned nextCursor.
list_integrations: page through integration records with {"limit":5}, then {"limit":5,"cursor":"RETURNED_CURSOR"}.
get_methodology: read {"id":"public-developer-surface"} or {"id":"capability-verification"}.

Request a free report

Call create_audit_session with {}. Save the returned private sessionToken before starting. A client does not need to maintain cookies for MCP.

Call request_free_report with {"sessionToken":"SAVED_TOKEN","website":"https://your-business.example/","requestId":"YOUR_UUID"}. Generate one UUID for this request and save it with the token. The service returns a reportId and its current state.

Call get_free_report with {"sessionToken":"SAVED_TOKEN","reportId":"RETURNED_REPORT_ID"}. While the report is queued or running, wait before checking the same report again. Honor any retryAt. Read the diagnosis when the state is complete; useful_partial includes the service's stated limitations. An accepted request alone is not a finished report.

If a start response is lost, repeat the same website, token and request ID to recover the original report. Keep the token private and out of URLs. Report access, website retrieval protections and generation limits are shared with the website's free audit.

Subscribe for your user

Call get_service_guide with {} to read current availability and the subscription steps. The same guide is available at /.well-known/aips-agent.json.

With the buyer's authorization, use the existing account APIs to verify their email, claim the original report and confirm their business details. The guide describes the request bodies, saved revisions, terms, payment method and status checks. To carry an MCP report into the account API, send its session token as the aips_audit_browser cookie alongside the verified buyer session.

One business costs $99 per month or $900 per year after a card-backed 72-hour trial. The buyer must authorize recurring payments. A browser-capable agent can use Stripe's secure card fields; an HTTP client needs a compatible card token for AIPS. A bank may require the cardholder to verify the card. Confirm the original subscription and invoice, finish business setup, and read service eligibility before reporting success.

Build for clear limits

Requests are limited to 64 KiB and responses to 256 KiB. Documentation search accepts 2–160 characters and returns up to 10 results. Unknown arguments and invalid cursors are rejected; correct the request or restart pagination without a cursor.

REST allows 120 requests per IP per minute, 300 total per minute and 5,000 per UTC day. MCP allows 60 per IP per minute, 120 total per minute and 3,000 per UTC day. These defensive ceilings apply per web process. HTTP 429 includes Retry-After and an error reset time. Wait until then before retrying.

REST errors include a code, message and correlation ID. MCP protocol errors use JSON-RPC error codes; a missing tool record returns isError: true. GET on /mcp returns 405 because this service does not stream. Browser requests must come from the public site's own origin.

Read availability precisely

A catalog record tells you what a capability means. It does not prove a live customer connection. Source-backed capabilities remain contract_ready with verification.state: unverified until separate native evidence establishes availability. Use the report tools for a website review and the service guide for current subscription availability.

Plan around the record's limitations and use your account for connection status. Public MCP never accepts account passwords or card details. Account and payment actions use the separate authenticated APIs described in the service guide.