Submissions & the API

When someone submits through a brief, Disclose Bot creates a report in your organization’s inbox.

What a submission becomes

A submission becomes a report with the reporter’s title, description, optional contact email, and the affected domain(s), linked back to the brief it came through.

The report lifecycle

Each report has two independent states:

• Processing: open → closed (and back via reopen). This is your triage status: open while you’re working it, closed when it’s resolved or declined.
• Inbox: dispatching → received → stored. This tracks how far the report has progressed through intake and storage.

Processing:  open ⇆ closed
Inbox:       dispatching → received → stored

Managing briefs and reports via the API

The Platform API exposes both, in JSON:API format, behind a Bearer token:

• Briefs: GET/POST/PATCH/DELETE /v1/briefs to manage briefs programmatically.
• Reports: GET/PATCH/DELETE /v1/reports to read and triage submissions, plus nested file management under a report.

List recent reports

curl https://api.disclosebot.io/v1/reports \
  -H "Authorization: Bearer disclosebot_svc_xxxxxxxx"

The list and single-report endpoints return reports within your plan’s report history window: the last 30 days on the Free plan, every report on paid plans. Older reports are kept, not deleted. meta.archived_count on the list response is the number of reports beyond the window, and a single report beyond it returns 404 until a plan with a longer window includes it again.

Published briefs are also readable without authentication via the public API:

Fetch a published brief

curl https://api.disclosebot.io/v1/p/briefs/<shortcode>

The document carries the brief’s description, rules_of_engagement, and submission_policy as markdown, each with a rendered, sanitized _html counterpart (description_html and so on), the scope lists, linked policies, public_url (the hosted page), and branding. The brief embed, the mini-brief button, and the hosted brief page all read this document.

File a report

Every widget mount files reports through the same public endpoint, a nested create on the brief. It needs no authentication, accepts a JSON:API document, and is rate limited per address (5 a minute, 30 an hour):

File a report against a published brief

curl https://api.disclosebot.io/v1/p/briefs/<shortcode>/reports \
  -H "Content-Type: application/vnd.api+json" \
  -d '{"data":{"type":"report","attributes":{"title":"Open redirect on login","description":"Steps to reproduce...","reporter_email":"you@example.com"},"relationships":{"assets":{"data":[{"type":"asset","id":"<asset id>"}]}}}}'

title and description are required; reporter_email and the assets relationship (ids from the brief’s own assets) are optional. The response is 201 with a report document carrying only the report’s shortcode; validation problems come back as 422 JSON:API errors, an unpublished or unknown brief as 404, and too many submissions as 429.

See the API quickstart for authentication and conventions, and the Platform API reference for the full schema.