feat: RD-158084 add Researcher API reference as a separate docs product - #14
Open
synack-tle wants to merge 3 commits into
Open
synack-tle wants to merge 3 commits into
synack-tle wants to merge 3 commits into
Conversation
Adds the 500 response, the archived-category and too-many-attachments problem types, the in-progress idempotency case, and the validationSteps limit. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Mintlify page URLs come from the file path, not the navigation tree; for OpenAPI-generated pages the object form of `openapi` sets that path via `directory`. So a distinct /platform URL space for SRTs needs no second Mintlify project and no reverse proxy. - navigation.tabs -> navigation.products, one product per audience. Mintlify scopes tabs to a single audience and products to separate offerings with their own full navigation, which is what two audiences need. It also gives RD-156367 somewhere to put SRT guides that customers will not see. - researcher spec moves to the object form with directory "platform", so its endpoints render under /platform/... instead of sharing /api-reference/... with the client specs. This also retires a latent slug collision: monolith-v1 has GET /v1/vulnerabilities and the researcher spec has POST on the same path, and they only avoid colliding today because the methods differ. - sync researcher-v1-openapi.yaml from synack_synack docs/platform/v1/openapi.yaml @ 5b56952639, which is the source of truth. This adds the srt_public_api scope requirement and the attachment size limits, and drops the Idempotency-Key header and 409 response, which are documented here but not implemented in synack_synack. - keep only the two production servers, matching the other specs in this repo. The backend copy also lists dev, QA and staging hosts, which should not be published or offered in "Try it". Verified with mint 4.2.588: both products render, the two researcher endpoints resolve under /platform, all 91 client /api-reference URLs are byte-identical to main, and mint broken-links reports the same 3 pre-existing failures as main (all in unpublished essentials/ starter-kit files). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
synack-tle
force-pushed
the
feature/RD-158084-researcher-api-reference
branch
from
September 1, 2026 00:59
b5f20dd to
9fa3f0f
Compare
synack-tle
marked this pull request as ready for review
September 1, 2026 01:01
synack-tle
requested review from
apapkov-synack,
humestc and
synack-ahull
as code owners
September 1, 2026 01:01
|
|
||
| It currently exposes vulnerability submission and the attachment upload that | ||
| supports it. Every operation is scoped to the researcher who owns the bearer | ||
| token; nothing in a request body can change that attribution. |
There was a problem hiding this comment.
Is that "... nothing..." statement necessary? Is saying that "every operation is scoped to the researcher" is not sufficient?
|
|
||
| Send a bearer token in the `Authorization` header. The token must be issued for this | ||
| API, carrying the `srt_public_api` scope; a session token is rejected with `403`, and | ||
| a token issued for this API cannot be used against the session API. |
There was a problem hiding this comment.
Why does this mention a session token? Is that relevant?
| - url: https://platform.synack.us/api | ||
| description: FedRAMP (Medium) | ||
| security: | ||
| - bearerAuth: [] |
|
|
||
| ## Errors | ||
|
|
||
| Errors follow RFC 7807 and are returned as `application/problem+json`. Validation |
There was a problem hiding this comment.
Can we link to the actual RFC doc here for convenience? https://datatracker.ietf.org/doc/html/rfc7807
|
|
||
| Errors follow RFC 7807 and are returned as `application/problem+json`. Validation | ||
| failures are `422 Unprocessable Content` and carry an `invalidParams` array naming | ||
| each offending field with the public (camelCase) name used in the request. |
There was a problem hiding this comment.
"public (camelCase) name used in the request" seems a bit excessive, right? "naming each ... field" does seem to imply exactly that, since exposing internal names would be weird in an API response.
| type: object | ||
| description: | | ||
| Reserved for response metadata such as pagination. Always an empty object for these | ||
| operations. |
There was a problem hiding this comment.
If it is not used, why expose it?
| type: string | ||
| format: uri | ||
| description: Signed download URL, valid for two hours. | ||
| example: https://storage.googleapis.com/synack-attachments/8412773/login-bypass.png?X-Goog-Expires=7200 |
There was a problem hiding this comment.
Is it valid for two hours because of the X-Goog-Expires=7200 parameter? Is that relevant for this request?
| resolvedAt: | ||
| type: string | ||
| format: date-time | ||
| description: RFC 3339 resolution timestamp. Absent until the vulnerability is resolved. |
There was a problem hiding this comment.
Can we add that the the timestamp must carry a timezone identifier or UTC offset?
| format: int64 | ||
| description: Identifier of the vulnerability. | ||
| example: 918273 | ||
| listingId: |
There was a problem hiding this comment.
Do we not use the term assessment now?
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Jira Tickets