> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recoupable.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Recoup public website API

> Search and read public Recoup content, use bounded website tools, and batch independent operations without an account.

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](/quickstart) and [platform MCP](/mcp-oauth). Website tools cannot
read account data, manage artists, publish content, or send an inquiry.

## Specification and first request

The [website OpenAPI specification](https://recoupable.dev/openapi.json) defines
every HTTP operation, its input and response schemas, and typed errors.
The [API catalog](https://recoupable.dev/.well-known/api-catalog) links this
specification alongside the platform specifications.

```bash theme={null}
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](https://recoupable.dev/agents.md) 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.

```bash theme={null}
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](https://recoupable.dev/agents.md) 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](https://recoupable.dev/.well-known/mcp.json) identifies
the server. Its five tools share the website HTTP capabilities and hosted quota.
To use your music-platform account, follow [MCP OAuth](/mcp-oauth) instead.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.