Documentation

Mortar serves Mosaic bounty data over HTTP and websocket. Contract state remains settlement authority.

HTTP Routes

Method	Route	Return
`GET`	`/health`	Service status and indexer flags.
`GET`	`/bounties`	Bounty records or a paged bounty response.
`GET`	`/bounties/{bounty_id}`	One bounty record.
`GET`	`/bounties/{bounty_id}/overview`	One bounty, its submissions, and their disputes.
`GET`	`/submissions`	Submission records or a paged submission response.
`GET`	`/submissions?bounty_id={id}`	Submission records for one bounty.
`GET`	`/submissions/{submission_id}`	One submission record.
`GET`	`/submissions/{submission_id}/overview`	One submission, its bounty, and its disputes.
`GET`	`/disputes`	Dispute records or a paged dispute response.
`GET`	`/disputes?bounty_id={id}`	Paged dispute records for one bounty.
`GET`	`/disputes?submission_id={id}`	Dispute records for one submission.
`GET`	`/disputes/{dispute_id}`	One dispute record.
`GET`	`/disputes/{dispute_id}/overview`	One dispute, its submission, its bounty, and sibling disputes.

Single-record and overview routes return 404 when the target record is unavailable.

List Query Params

List routes accept:

Param	Meaning
`limit`	Page size from `1` to `100`. Defaults to `50` for paged responses.
`cursor`	Offset cursor returned by a prior page. Invalid cursors read from `0`.
`q`	Text search across IDs, status, actors, metadata, transaction hash, and route-specific text fields.
`sort`	Sort key. Unknown values use `id`.
`dir`	`asc` or `desc`. Unknown values use `desc`.

GET /bounties, GET /submissions, and GET /disputes return legacy arrays when no paging or search params are supplied. Supplying limit, cursor, or q returns a page object. GET /disputes?bounty_id=... also returns a page object.

Page object:

{
  "items": [],
  "total": 0,
  "limit": 50,
  "cursor": null,
  "next_cursor": null
}

Bounty page rows include submission_count. Submission page rows and submission overview records include dispute_count.

Sort keys:

Bounties: id, created_at, deadline, reward, bounty_amount, bond, bond_amount, status, poster, prompt, submissions, submission_count.
Submissions: id, created_at, submitted, bounty, bounty_id, bond, bond_amount, status, claimant, content, review, review_deadline, disputes, dispute_count.
Disputes: id, created_at, submitted, bounty, bounty_id, submission, submission_id, bond, bond_amount, status, challenger, reason.

Bounty Fields

Field	Meaning
`id`	Bounty ID.
`prompt`	Stored prompt field. Current indexer mirrors `metadata_uri` here.
`bounty_amount`	Reward amount in USDC base units.
`fee_amount`	Post fee amount in USDC base units.
`bond_amount`	Submission bond in USDC base units.
`duration`	Bounty duration in seconds.
`status`	`open`, `resolved`, or `refunded`.
`poster`	Poster address.
`deadline`	Bounty deadline timestamp.
`challenge_window`	Review window in seconds.
`metadata_uri`	Bounty metadata URI.
`metadata_hash`	Bounty metadata hash.
`tx_hash`	Source transaction hash.
`block_number`	Source block number.
`log_index`	Source log index.
`created_at`	Mortar row creation timestamp.
`submission_count`	Included on paged and overview bounty records.

Submission Fields

Field	Meaning
`id`	Submission ID.
`bounty_id`	Parent bounty ID.
`tile_id`	Submitter address field.
`content`	Stored content field. Current indexer mirrors `metadata_uri` here.
`bond_amount`	Submission bond in USDC base units.
`review_deadline`	Submission review deadline timestamp.
`status`	`submitted`, `disputed`, `accepted`, `rejected`, or `refunded`.
`claimant`	Submitter address.
`metadata_uri`	Submission metadata URI.
`metadata_hash`	Submission metadata hash.
`tx_hash`	Source transaction hash.
`block_number`	Source block number.
`log_index`	Source log index.
`created_at`	Mortar row creation timestamp.
`dispute_count`	Included on paged and overview submission records.

Dispute Fields

Field	Meaning
`id`	Dispute ID.
`bounty_id`	Parent bounty ID.
`submission_id`	Disputed submission ID.
`challenger_id`	Grout address.
`reason`	Stored reason field. Current indexer mirrors `metadata_uri` here.
`bond_amount`	Dispute bond in USDC base units.
`status`	`pending_human_review`, `upheld`, `rejected`, or `cancelled`.
`metadata_uri`	Dispute metadata URI.
`metadata_hash`	Dispute metadata hash.
`tx_hash`	Source transaction hash.
`block_number`	Source block number.
`log_index`	Source log index.
`created_at`	Mortar row creation timestamp.

HTTP Caching and Limits

Read responses include Cache-Control and weak ETag headers. Supplying a matching If-None-Match returns 304.

HTTP rate limits apply to every route except /health. Rate-limited responses return 429 with Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Websocket

WS /ws/events

Connection sequence:

Current bounty records.
Current submission records.
Current dispute records.
Live updates.

Websocket connection and message limits close the socket with code 1008 when exceeded.

Websocket Payloads

Type	Payload
`bounty.created`	Bounty record.
`submission.created`	Submission record.
`dispute.created`	Dispute record.
`dispute.resolved`	Dispute record.
`dispute.cancelled`	Dispute record.
`bounty.finalized`	Bounty record.
`bounty.refunded`	Bounty record.
`submission.refunded`	Submission record.

Mortar API