Recoup public website API

The public website API searches and reads published Recoup pages, calculates workflow scenarios from supplied inputs, and prepares unsubmitted project briefs. It is free and requires no account, API key, or payment method. Music-platform operations use the separate authenticated platform API and platform MCP. Website tools cannot read account data, manage artists, publish content, or send an inquiry.

Specification and first request

The website OpenAPI specification defines every HTTP operation, its input and response schemas, and typed errors. The API catalog links this specification alongside the platform specifications.

curl -i 'https://recoupable.dev/agent-api/v1/search?query=royalty&limit=1'

The response contains results, total, and nextCursor. An empty result list is a successful search. Use a returned content ID with GET /agent-api/v1/read?id=CONTENT_ID; continue at the returned nextOffset until it is null. The reader accepts registry IDs, never arbitrary private URLs. Use GET /agent-api/v1/markdown?path=/blog for a complete public page as Markdown. The website agent guide explains all five tools, pagination, draft behavior, and the browser interface.

Batch independent operations

POST https://recoupable.dev/agent-api/v1/batch accepts one to ten operations.

curl 'https://recoupable.dev/agent-api/v1/batch' \
  -H 'Content-Type: application/json' \
  --data '{"operations":[{"name":"search_recoup","arguments":{"query":"royalty","limit":1}},{"name":"read_recoup_page","arguments":{"id":"page:/services","maxLength":500}}]}'

The results array preserves input order. Each entry has its own status and result or error. An individual failure does not cancel successful reads. The batch is not a transaction. Its entire request body must fit within 16 KB. Draft operations return submitted: false; nothing is sent or saved as a lead.

Hosted quotas and errors

HTTP and MCP website tools share a limit of 120 requests per 60-second fixed window, per IP address and serving region. A batch counts as one request. RateLimit-Limit and RateLimit-Policy describe that enforced policy on live responses. Regional counters are not a global account allowance. On HTTP 429, wait the Retry-After duration before retrying. HTTP 503 means the request could not be completed; retry later. JSON tool endpoints return structured errors with a code, message, and recovery guidance for invalid arguments or missing content. Local development does not enforce the hosted quota.

Versioning and deprecation

Website HTTP operations use /agent-api/v1. Additive response fields are compatible; clients should ignore fields they do not recognize. Incompatible changes require a new major URL version. No v1 deprecation or sunset is scheduled. A future retirement will be announced in the agent guide with a migration guide and Deprecation, Sunset, and Link response headers when dates are known. This policy applies to the public website API.

MCP connection

Connect to https://recoupable.dev/mcp over Streamable HTTP without credentials. The public manifest identifies the server. Its five tools share the website HTTP capabilities and hosted quota. To use your music-platform account, follow MCP OAuth instead.

​Specification and first request

​Batch independent operations

​Hosted quotas and errors

​Versioning and deprecation

​MCP connection

Specification and first request

Batch independent operations

Hosted quotas and errors

Versioning and deprecation

MCP connection