Update a custom API source
Update only the supplied fields of a custom source. Team admins only. A change of documentation, request template (authentication included), pagination or mapping increments configuration_version, marks the previous test stale, and pauses synchronization until the new configuration passes a test. A change of the request URL’s origin (scheme, host, port), the OAuth token URL’s origin, or the authentication type, header name or query parameter name also revokes the stored credential (credential_configured becomes false): send the credential again with the test action. enabled false disables the source, stops its schedule and cancels its queued synchronizations; enabled true re-enables a source whose current configuration passed a test (409 source_not_tested otherwise) and makes it due at once. documentation_append adds files to the stored documentation.
Authorizations
JWT authentication token
Path Parameters
Source id
Body
Only supplied fields change.
{"note": "..."} acknowledges the source's current content gaps (the server records who, when and the gaps); null clears the acknowledgement.
Per-record detail request of a custom API source. {"request_template": {"method", "url", "headers", "query", "auth"}, "items_path", "mapping", "budget"}: the template may use {{item.}} (a value of the listed record) and {{item.external_key}}; the mapping (a subset of the source mapping) overrides the list mapping; budget is the most records one synchronization fetches (default 500, at most 2000). Detail runs only for new or changed records. In a PATCH, null removes it.
Reference to the API documentation: public https links, a brief (inline) and attached files (at most 1 MiB of text together). Never include a credential. On PATCH it replaces the stored links and brief, and the files when files is given; documentation_append adds files.
Custom API sources: files to add to documentation.files (an attached spec, more notes), redacted like inline. It counts as a documentation change like setup_answer and may come with it. 422 documentation_too_large when the documentation would pass 1 MiB or 10 files.
false disables the source and stops its schedule; true re-enables a source whose current configuration passed a test.
A second listing of a custom API source whose rows are matched to the listed records. {"request_template", "pagination", "items_path", "key", "item_key", "mapping"}: a row whose key equals the record's item_key fills the record's empty fields with its mapping. It is fetched once per synchronization. In a PATCH, null removes it.
Dot paths from each provider record to the normalized finding fields (mapping v2). external_key identifies a record inside the source. A text field takes one path or an ordered list; url also takes a template. A mapping written for the first version (strings only) stays valid.
1 - 80How a synchronization walks the listing.
The request a synchronization sends. Header and query values are stored and returned as typed, so never put a credential in them.
Interval between scheduled synchronizations.
1h, 6h, 12h, 24h Custom API sources: the user's answer to the setup question (setup_report.question), for example "Chosen: GET /v1/scans/results". It is appended to documentation.answers (the newest 10 are kept) with obvious credentials redacted, and counts as a documentation change: configuration_version goes up and the source is analyzed again from the documentation and every answer.
1 - 500documentation reads an OpenAPI 3 or Swagger 2 document to propose the configuration; manual takes the configuration as entered. update is only ever returned, never accepted: a ready or needs_attention source shows it while a setup run (POST /analyze, or a setup answer) is queued or running. The source keeps its status and its configuration and keeps synchronizing; the new configuration replaces the old only when the run ends configured with a passing test.
documentation, manual, update Requests sent in order before the findings request (a login, a token exchange), at setup and at every synchronization. Values a step captures, the credential fields and the secrets given with the test action are used as {{$name}} placeholders in header values, query values, the URL path and query, and body strings of later steps and of request_template.
3Response
The updated source
A Triage source of your team. Credentials are never returned: credential_configured shows whether one is stored.
Incremented by every change of documentation, request template, pagination or mapping.
Names of the stored credential's entries, never a value: the credential fields that hold one (api_key, token, username, password, client_id, client_secret), then the names of the secrets given with the test action, sorted. Empty when no credential is stored.
The name to show: the display name set in the source settings, or the source name when none is set. Inbox listings keep writing the provider name to name; they never change the display name.
Documentation reference of a source. Pasted documents are not returned.
True when scheduled synchronization is on.
hackerone, github and gmail are built-in connections; custom_api is a source you configure.
hackerone, github, gmail, custom_api, scanner Interval between scheduled synchronizations.
1h, 6h, 12h, 24h documentation reads an OpenAPI 3 or Swagger 2 document to propose the configuration; manual takes the configuration as entered. update is only ever returned, never accepted: a ready or needs_attention source shows it while a setup run (POST /analyze, or a setup answer) is queued or running. The source keeps its status and its configuration and keeps synchronizing; the new configuration replaces the old only when the run ends configured with a passing test.
documentation, manual, update Server-controlled lifecycle state of a source. needs_attention is a ready source whose last synchronization left a content gap nobody acknowledged (coverage.gaps holds body and content_ack is not set) or dropped values (a dropped: gap); it synchronizes, enables and disables exactly like ready, and returns to ready when a later synchronization or remap has no such gap, or when the gap is acknowledged. With the setup assistant on, an analysis that works out a configuration moves on to testing, and a test that verifies it moves a source that was never enabled on to setting_up (the source is enabled and its first synchronization runs); an enabled source goes back to ready. A disabled source keeps its status. A failed scheduled or manual synchronization sets failed and backs the next one off (the schedule interval times 2^min(failures, 4), at most 24 hours later). After 10 failed synchronizations in a row the source is paused: disabled, enabled false, last_error_code kept. A successful synchronization or re-enabling the source resets the count.
draft, analyzing, configuration_required, testing, setting_up, ready, needs_attention, syncing, failed, disabled, removed Configuration version that last passed a test (0 when none). Synchronization needs it to equal configuration_version.
The auto triage rule of a source as the source list shows it.
The acknowledgement of the source's content gaps, null when none.
Content coverage of the last synchronization or remap; null before the first one.
The analyze or test job of this source that is queued or running, null when none.
Per-record detail request of a custom API source. {"request_template": {"method", "url", "headers", "query", "auth"}, "items_path", "mapping", "budget"}: the template may use {{item.}} (a value of the listed record) and {{item.external_key}}; the mapping (a subset of the source mapping) overrides the list mapping; budget is the most records one synchronization fetches (default 500, at most 2000). Detail runs only for new or changed records. In a PATCH, null removes it.
A second listing of a custom API source whose rows are matched to the listed records. {"request_template", "pagination", "items_path", "key", "item_key", "mapping"}: a row whose key equals the record's item_key fills the record's empty fields with its mapping. It is fetched once per synchronization. In a PATCH, null removes it.
Stable code of the last failure, such as target_not_public or upstream_status. On a ready source it is a warning from the last synchronization, such as record_limit or page_limit when the listing was longer than one synchronization reads.
Dot paths from each provider record to the normalized finding fields (mapping v2). external_key identifies a record inside the source. A text field takes one path or an ordered list; url also takes a template. A mapping written for the first version (strings only) stays valid.
Custom API sources: the next scheduled synchronization. HackerOne and Security Inbox sources: the next refresh of the built-in refresh job, which reads the first page of the connection. GitHub sources are refreshed by listing only.
How a synchronization walks the listing.
Set on a custom API source whose configuration Neo writes and keeps (a connected Bugcrowd account). Its documentation, request template, pagination, mapping and steps cannot be changed, and it is not analyzed.
bugcrowd The request a synchronization sends. Header and query values are stored and returned as typed, so never put a credential in them.
Present only when kind is scanner.
Custom API sources with the source-setup agent on: the outcome of the last analysis or test run, in plain terms. Absent until one finished.
Requests sent in order before the findings request (a login, a token exchange), at setup and at every synchronization. Values a step captures, the credential fields and the secrets given with the test action are used as {{$name}} placeholders in header values, query values, the URL path and query, and body strings of later steps and of request_template.
3
