# Earshot

Earshot lets developers select eligible Public Discord Server Archives and
query the history and live updates it can observe. Earshot operates the
Discord-authorized bots, records new activity, and reports known Coverage
limits. One API credential works with REST and hosted MCP. Earshot does not
post to Discord.

Canonical: https://earshot.gg

## API (planned REST base: https://api.earshot.gg)

- GET /v1/servers/:server_id/messages - list current archived messages; filters:
  channel_id, before, after, created_before, created_after, limit, and cursor
- GET /v1/servers/:server_id/messages/:message_id - fetch one current archived message
- GET /v1/servers/:server_id/search?q= - full-text search over current archived
  message content; optional channel_id, before, and limit
- GET /v1/servers/:server_id/channels - list channels visible to the credential
- GET /v1/servers/:server_id/coverage - detailed per-channel Coverage; optional
  channel_id, limit, and cursor

Every successful v1 REST response uses four top-level fields: data, page,
coverage, and as_of. page contains next_cursor. coverage summarizes the archive
data visible to the credential. as_of contains decimal-string archive_revision
and the archive incarnation UUID. Message data contains decimal-string
message_id and channel_id, content, discord_created_at, and discord_edited_at.
Continuation cursors are opaque signed tokens. Pass next_cursor back as cursor
with the same endpoint, credential, Server, and filters; do not inspect or edit
it.

Authenticate with `Authorization: Bearer esk_...`. An API credential limits
allowed actions. Its principal's access grants limit Server and channel access.
REST and MCP reads use the same fail-closed query policy.

V1 treats a Server as Public when Discord's observed Server data includes the
DISCOVERABLE feature. A Customer Account may select an eligible Public Server
Archive within its allowance. Query access begins after the first archive
commit and continues while Historical Sync runs or if the Connection later
ends; Coverage reports the acquisition boundary.

## MCP (planned: https://api.earshot.gg/mcp)

Hosted Streamable HTTP MCP at `/mcp`, authenticated with the same `esk_...`
bearer credential and access policy as REST. Read-only tools are
`search_messages`, `get_messages`, and `list_channels`. One MCP tool call counts
as one API request. MCP initialization and tool discovery do not consume usage.

## Demo

The planned demo server will use a shared read-only credential and require no
account. Under the candidate commercial policy, other Public Server Archives
require paid Server Access.

## Candidate pricing

- Starter: access to 3 Server Archives, 100k requests/month
- Pro: access to 25 Server Archives, 1M requests/month
- Enterprise: custom limits and terms

Pricing and public launch depend on Discord approval/App Review and legal review
of Earshot's archival, sharing, and commercial behavior.

## Facts and limits

- V1 acquisition uses Discord-authorized Bot Connections operated by Earshot.
  Pasting a public invite link is not a supported acquisition path.
- Earshot cannot recover content deleted before observation, inaccessible
  content, every prior edit, or every event missed across a non-resumable live
  gap. Coverage reports known limits.
- Threads, permissions, privileged Discord capabilities, and Earshot's selected
  channel scope affect what Earshot can observe.
- Revoking an access grant blocks future Earshot reads.
- Server Access release/cancellation, grant revocation, Connection pause, and
  archive erasure are separate operations. Retention/erasure policy is not yet
  finalized.
- FAQ: https://earshot.gg/faq