Skip to content
Disclose Bot

API quickstart

The Platform API is a JSON:API over HTTPS. This page covers the base URL, authentication, and conventions. For the full schema, see the Platform API reference.

Base URL

Section titled “Base URL”
https://api.disclosebot.io/v1

Authentication

Section titled “Authentication”

Authenticated requests use a Bearer token in the Authorization header:

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

Tokens are prefixed by the kind of holder they belong to:

PrefixHolder
disclosebot_svc_…An organization service account token (server-to-server integration).

Create service accounts and mint tokens from API Service Accounts in the app. Treat tokens as secrets; keep them out of source control and rotate them if exposed.

Conventions

Section titled “Conventions”
  • Format: requests and responses follow JSON:API. Send and accept application/vnd.api+json.
  • Resources: the API exposes policies, briefs, reports, assets, organizations, directory_listings, channels (see the Channels API), saved_searches (see the Saved Searches API), and more. See the reference for the full list and schemas.
  • Relationships and filtering follow JSON:API conventions; filters are ransack predicates under q[...] on the attributes each endpoint lists.
  • Pagination is described below.

Pagination

Section titled “Pagination”

Every paginated list endpoint takes page[number] (from 1) and page[size] (default and maximum 30), and its response carries meta.pagination and links. Two lists are a single page, ignore page[...] and carry no meta.pagination (their links hold self only): GET /v1/organizations (the organization the token belongs to) and GET /v1/webhook_event_types.

Paginated list response
{
  "data": [ "..." ],
  "meta": {
    "pagination": {
      "current": 2,
      "first": 1,
      "prev": 1,
      "next": 3,
      "last": 5,
      "records": 134
    }
  },
  "links": {
    "self": "https://api.disclosebot.io/v1/public_keys?page[number]=2&page[size]=30",
    "first": "https://api.disclosebot.io/v1/public_keys?page[number]=1&page[size]=30",
    "prev": "https://api.disclosebot.io/v1/public_keys?page[number]=1&page[size]=30",
    "next": "https://api.disclosebot.io/v1/public_keys?page[number]=3&page[size]=30",
    "last": "https://api.disclosebot.io/v1/public_keys?page[number]=5&page[size]=30"
  }
}
  • meta.pagination.records is the total number of records across every page, after filters.
  • meta.pagination.current is the page returned. first and prev appear after the first page; next and last appear before the last page.
  • links carry the same pages as URLs, with the request’s filters and sort preserved.

To read a count without the rows, request page[size]=1 and read meta.pagination.records.

Errors

Section titled “Errors”

Errors come back as a JSON:API errors array. Two are specific to the platform:

  • 403 with title Feature not available: the operation is behind a feature that is not enabled for your account.
  • 403 with code: "upgrade_required": the operation needs a plan entitlement your current plan does not include. meta.feature names the entitlement (for example automation) and meta.required_plan names the lowest plan that includes it. Change the plan from Billing in the admin app.
Upgrade required
{
  "errors": [
    {
      "title": "Upgrade required",
      "detail": "Automated processing is not included on the current plan",
      "code": "upgrade_required",
      "status": "403",
      "meta": { "feature": "automation", "required_plan": "pro" }
    }
  ]
}

Public read endpoints (no auth)

Section titled “Public read endpoints (no auth)”

Published policies, briefs, and portals can be read without a token, by id or shortcode:

Fetch a published policy, brief, or portal
curl https://api.disclosebot.io/v1/p/policies/<shortcode>
curl https://api.disclosebot.io/v1/p/briefs/<shortcode>
curl https://api.disclosebot.io/v1/p/portals/<shortcode>

These are the documents the embeddable widgets render (the hosted pages render the same document inline). Rendered text fields come with a sanitized _html counterpart next to the raw markdown (policy_html, description_html), every document carries public_url, branding, and attribution (whether the widget shows the “Powered by” mark), and an unpublished or unknown record is 404.

Embeds are a plan feature. Once paid plans are on sale, a read for an organization whose plan does not include embeds answers 403 with code: "upgrade_required"; its meta carries organization_name and public_url (the hosted page) so a widget can show a card linking there instead. The hosted pages themselves are always available.

Reports are filed without a token as well, through POST /v1/p/briefs/<shortcode>/reports (a JSON:API report document; see Briefs, submissions and the API). The endpoint is rate limited per address and answers 429 when the limit is reached.

Next

Section titled “Next”