Skip to main content
PATCH
Update a custom API source

Authorizations

Authorization
string
header
required

JWT authentication token

Path Parameters

id
string<uuid>
required

Source id

Body

application/json

Only supplied fields change.

content_ack
object | null

{"note": "..."} acknowledges the source's current content gaps (the server records who, when and the gaps); null clears the acknowledgement.

detail
object | null

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.

documentation
object

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.

documentation_append
object[]

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.

enabled
boolean

false disables the source and stops its schedule; true re-enables a source whose current configuration passed a test.

join
object | null

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.

mapping
object

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.

name
string
Required string length: 1 - 80
pagination
object

How a synchronization walks the listing.

request_template
object

The request a synchronization sends. Header and query values are stored and returned as typed, so never put a credential in them.

schedule
enum<string>

Interval between scheduled synchronizations.

Available options:
1h,
6h,
12h,
24h
setup_answer
string

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.

Required string length: 1 - 500
setup_mode
enum<string>

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.

Available options:
documentation,
manual,
update
steps
object[]

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.

Maximum array length: 3

Response

The updated source

A Triage source of your team. Credentials are never returned: credential_configured shows whether one is stored.

configuration_version
integer
required

Incremented by every change of documentation, request template, pagination or mapping.

created_at
string<date-time>
required
credential_configured
boolean
required
credential_names
string[]
required

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.

display_name
string
required

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
object
required

Documentation reference of a source. Pasted documents are not returned.

enabled
boolean
required

True when scheduled synchronization is on.

id
string<uuid>
required
kind
enum<string>
required

hackerone, github and gmail are built-in connections; custom_api is a source you configure.

Available options:
hackerone,
github,
gmail,
custom_api,
scanner
name
string
required
schedule
enum<string>
required

Interval between scheduled synchronizations.

Available options:
1h,
6h,
12h,
24h
setup_mode
enum<string>
required

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.

Available options:
documentation,
manual,
update
status
enum<string>
required

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.

Available options:
draft,
analyzing,
configuration_required,
testing,
setting_up,
ready,
needs_attention,
syncing,
failed,
disabled,
removed
team_id
string<uuid>
required
tested_configuration_version
integer
required

Configuration version that last passed a test (0 when none). Synchronization needs it to equal configuration_version.

updated_at
string<date-time>
required
auto_triage
object

The auto triage rule of a source as the source list shows it.

content_ack
object | null

The acknowledgement of the source's content gaps, null when none.

coverage
object | null

Content coverage of the last synchronization or remap; null before the first one.

coverage_at
string<date-time> | null
current_setup_job_id
string<uuid> | null

The analyze or test job of this source that is queued or running, null when none.

detail
object | null

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.

join
object | null

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.

last_error_code
string

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.

last_synced_at
string<date-time>
mapping
object

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.

next_sync_at
string<date-time>

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.

pagination
object

How a synchronization walks the listing.

preset
enum<string> | null

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.

Available options:
bugcrowd
request_template
object

The request a synchronization sends. Header and query values are stored and returned as typed, so never put a credential in them.

scanner
object

Present only when kind is scanner.

setup_report
object

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.

steps
object[]

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.

Maximum array length: 3