Skip to content

Openapi integration #40

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
TheMythologist wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Openapi integration #40

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d8a10e9
deps: upgrade mintlify
TheMythologist Jul 9, 2026
7f17da6
Openapi integration in Mintlify
TheMythologist Jul 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 1 addition & 86 deletions api-reference/cost-estimations/create-cost-estimation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Create cost estimation"
api: "POST /cost-estimations"
openapi: "POST /cost-estimations"
description: "Estimate the credit cost of scanning one or more repositories before starting a scan."
---

Expand All @@ -12,86 +12,6 @@ Cost estimations run asynchronously. The `POST` returns a record in `pending` or
**Scope required**: `write`
</Info>

## Request

```bash
curl -X POST https://api.hacktron.ai/v1/cost-estimations \
-H "X-Api-Key: $HACKTRON_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "nightly-estimate",
"repos": [
{
"source": "connected",
"repo_url": "https://github.com/acme/backend",
"branch": "main"
}
]
}'
```

### Body

| Field | Type | Required | Description |
| ------- | -------- | -------- | ------------------------------------------------------------------------------------------------ |
| `name` | string | No | Friendly label for this estimation. Max 255 chars. |
| `repos` | object[] | Yes | 1–20 repositories to estimate. Each entry is one of the repo shapes below, identified by `source`. |

### Repo shapes

Repositories use a discriminated union on the `source` field.

#### `connected` — a repository already synced to Hacktron via GitHub, GitLab, or Bitbucket

| Field | Type | Required | Description |
| ------------------------ | ------ | -------- | ---------------------------------------------------- |
| `source` | `"connected"` | Yes | Discriminator. |
| `repo_url` | string | Yes | Full HTTPS URL of the repository. Max 500 chars. |
| `branch` | string | Yes | Branch to estimate. Max 255 chars. |
| `github_installation_id` | int | No | Specific GitHub App installation ID to use. |

#### `public` — a public git repository Hacktron can clone anonymously

| Field | Type | Required | Description |
| ---------- | ------ | -------- | ----------------------------------------- |
| `source` | `"public"` | Yes | Discriminator. |
| `repo_url` | string | Yes | Full HTTPS URL. Max 500 chars. |
| `branch` | string | Yes | Branch to estimate. Max 255 chars. |

#### `upload` — a previously uploaded archive

| Field | Type | Required | Description |
| ------------ | ------ | -------- | ----------------------------------- |
| `source` | `"upload"` | Yes | Discriminator. |
| `archive_id` | UUID | Yes | ID of a scan archive you uploaded. |

## Response

`201 Created` — the estimation is queued. Poll `GET /cost-estimations/{id}` until `status` reaches a terminal value.

```json
{
"id": "b4f5c6a1-2d3e-4f56-9a8b-0c1d2e3f4a5b",
"organization_id": "f336d0bc-b841-465b-8045-024475c079dd",
"user_id": "e5a6d7c8-9b0a-1c2d-3e4f-5a6b7c8d9e0f",
"name": "nightly-estimate",
"task_id": "cost_est_acme-backend_1712345678",
"status": "pending",
"repos": [
{
"source": "connected",
"repo_url": "https://github.com/acme/backend",
"branch": "main"
}
],
"total_credits": null,
"repo_results": null,
"error": null,
"created_at": "2026-04-13T12:00:00.000Z",
"updated_at": "2026-04-13T12:00:00.000Z"
}
```

### Terminal statuses

| Status | Meaning |
Expand All @@ -101,8 +21,3 @@ Repositories use a discriminated union on the `source` field.
| `failed` | The whole estimation failed. `error` contains a message. |

Once in a terminal state, an estimation is immutable. Pass its `id` as `cost_estimation_id` to [`POST /scans`](/api-reference/scans/create-scan) to start the scan. The scan must use repositories and branches that were included in the estimate.

## Errors

- `400` — invalid or missing fields (for example, more than 20 repos, invalid `source`, or missing `repo_url`).
- `401` / `403` — authentication or scope failure.
62 changes: 1 addition & 61 deletions api-reference/cost-estimations/get-cost-estimation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Get cost estimation"
api: "GET /cost-estimations/{id}"
openapi: "GET /cost-estimations/{id}"
description: "Fetch a cost estimation by ID."
---

Expand All @@ -9,63 +9,3 @@ Returns a single cost estimation. Poll this endpoint on a pending estimation unt
<Info>
**Scope required**: `read`
</Info>

## Request

```bash
curl "https://api.hacktron.ai/v1/cost-estimations/b4f5c6a1-2d3e-4f56-9a8b-0c1d2e3f4a5b" \
-H "X-Api-Key: $HACKTRON_API_KEY"
```

### Path parameters

| Parameter | Type | Description |
| --------- | ---- | --------------------------------- |
| `id` | UUID | The cost estimation UUID. |

## Response

`200 OK` — see [Create cost estimation](/api-reference/cost-estimations/create-cost-estimation) for the response schema.

```json
{
"id": "b4f5c6a1-2d3e-4f56-9a8b-0c1d2e3f4a5b",
"organization_id": "f336d0bc-b841-465b-8045-024475c079dd",
"user_id": "e5a6d7c8-9b0a-1c2d-3e4f-5a6b7c8d9e0f",
"name": "nightly-estimate",
"task_id": "cost_est_acme-backend_1712345678",
"status": "completed",
"repos": [
{
"source": "connected",
"repo_url": "https://github.com/acme/backend",
"branch": "main",
"commit_sha": "abc123def456"
}
],
"total_credits": 4200,
"repo_results": [
{
"repo_url": "https://github.com/acme/backend",
"branch": "main",
"commit_sha": "abc123def456",
"status": "completed",
"from_cache": false,
"credits": 4200,
"applications": [
{
"app_name": "backend-api",
"app_root_path": "apps/api",
"architecture": "NestJS REST API with PostgreSQL"
}
]
}
],
"created_at": "2026-04-13T12:00:00.000Z",
"updated_at": "2026-04-13T12:03:21.000Z"
}
```

## Errors

- `404` — estimation not found or not visible to your organization.
73 changes: 1 addition & 72 deletions api-reference/cost-estimations/list-cost-estimations.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "List cost estimations"
api: "GET /cost-estimations"
openapi: "GET /cost-estimations"
description: "List cost estimations for your organization."
---

Expand All @@ -13,74 +13,3 @@ Returns cost estimations for the organization, most recent first. Use offset-bas
<Note>
Unlike most list endpoints, cost estimations use **offset‑based pagination** (`limit` + `offset`) instead of `page` + `limit`. See [Pagination, filtering & sorting](/api-reference/pagination-filtering) for the general conventions.
</Note>

## Request

```bash
curl "https://api.hacktron.ai/v1/cost-estimations?limit=20&offset=0" \
-H "X-Api-Key: $HACKTRON_API_KEY"
```

### Query parameters

| Parameter | Type | Default | Max | Description |
| --------- | ------- | ------- | --- | ------------------------------------ |
| `limit` | integer | `50` | `100` | Number of items to return. |
| `offset` | integer | `0` | — | Number of items to skip. |

## Response

`200 OK`

```json
{
"data": [
{
"id": "b4f5c6a1-2d3e-4f56-9a8b-0c1d2e3f4a5b",
"organization_id": "f336d0bc-b841-465b-8045-024475c079dd",
"user_id": "e5a6d7c8-9b0a-1c2d-3e4f-5a6b7c8d9e0f",
"name": "nightly-estimate",
"task_id": "cost_est_acme-backend_1712345678",
"status": "completed",
"repos": [
{
"source": "connected",
"repo_url": "https://github.com/acme/backend",
"branch": "main",
"commit_sha": "abc123def456"
}
],
"total_credits": 4200,
"repo_results": [
{
"repo_url": "https://github.com/acme/backend",
"branch": "main",
"commit_sha": "abc123def456",
"status": "completed",
"from_cache": false,
"credits": 4200,
"applications": [
{
"app_name": "backend-api",
"app_root_path": "apps/api",
"architecture": "NestJS REST API with PostgreSQL"
}
]
}
],
"created_at": "2026-04-13T12:00:00.000Z",
"updated_at": "2026-04-13T12:03:21.000Z"
}
],
"total": 42
}
```

### Fields

| Field | Type | Description |
| ------- | -------- | --------------------------------------------------- |
| `data` | object[] | The estimations on this page. |
| `total` | integer | Total number of estimations in the organization. |

See [Create cost estimation](/api-reference/cost-estimations/create-cost-estimation) for the full estimation object shape.
42 changes: 1 addition & 41 deletions api-reference/findings/add-finding-comment.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Add finding comment"
api: "POST /findings/{id}/comments"
openapi: "POST /findings/{id}/comments"
description: "Append a comment to a finding's triage thread."
---

Expand All @@ -9,43 +9,3 @@ Appends a comment to a finding's triage thread. Comments appear in the dashboard
<Info>
**Scope required**: `write`
</Info>

## Request

```bash
curl -X POST https://api.hacktron.ai/v1/findings/d1e2f3a4-b5c6-7890-1234-567890abcdef/comments \
-H "X-Api-Key: $HACKTRON_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"comment": "Confirmed reproducible on staging. Opened JIRA-4821."
}'
```

### Path parameters

| Parameter | Type | Description |
| --------- | ---- | ----------------- |
| `id` | UUID | Finding UUID. |

### Body

| Field | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------ |
| `comment` | string | Yes | Comment text. 1–4000 characters. |

## Response

`201 Created`

```json
{
"comment_id": "c0ffee01-feed-4bad-badc-0ffee0000002"
}
```

The comment is tagged with `source: "api"` and attributed to the API key's creator. It then appears in the finding's [`triage_thread`](/api-reference/findings/get-finding).

## Errors

- `400` — comment missing or exceeds 4000 characters.
- `404` — finding not found or not visible to your organization.
78 changes: 1 addition & 77 deletions api-reference/findings/get-finding.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Get finding"
api: "GET /findings/{id}"
openapi: "GET /findings/{id}"
description: "Fetch a single finding with full triage context."
---

Expand All @@ -9,79 +9,3 @@ Returns a single finding along with its triage thread, occurrence count, reposit
<Info>
**Scope required**: `read`
</Info>

## Request

```bash
curl "https://api.hacktron.ai/v1/findings/d1e2f3a4-b5c6-7890-1234-567890abcdef" \
-H "X-Api-Key: $HACKTRON_API_KEY"
```

### Path parameters

| Parameter | Type | Description |
| --------- | ---- | ----------------- |
| `id` | UUID | Finding UUID. |

## Response

`200 OK` — all the fields from [List findings](/api-reference/findings/list-findings#finding-fields), plus:

```json
{
"id": "d1e2f3a4-b5c6-7890-1234-567890abcdef",
"title": "SQL injection in /api/v1/checkout",
"category": "injection",
"severity": "critical",
"state": "open",
"description": "...",
"affected_file": "apps/api/src/checkout/checkout.service.ts",
"affected_code": "...",
"proof_of_concept": "...",
"tags": ["injection", "sql"],
"scan_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"found_at": "2026-04-13T12:15:00.000Z",
"updated_at": "2026-04-13T12:20:00.000Z",
"triage_thread": [
{
"id": "c0ffee01-feed-4bad-badc-0ffee0000001",
"reaction": null,
"comment": "Confirmed reproducible on staging — cart_id=1' OR '1'='1 returns 200 with full row dump.",
"user_id": "e5a6d7c8-9b0a-1c2d-3e4f-5a6b7c8d9e0f",
"username": "alex",
"source": "api",
"timestamp": "2026-04-13T12:22:00.000Z"
}
],
"mermaid_trace": "graph TD\n A[Request] --> B[checkout.service.ts]\n B --> C[(Postgres)]",
"occurrence_count": 1,
"repo_url": "https://github.com/acme/backend",
"scan_type": "full"
}
```

### Extra fields

| Field | Type | Description |
| ------------------ | --------------- | --------------------------------------------------------------------------------------------- |
| `triage_thread` | object[] | Comments and reactions on the finding, aggregated across GitHub, Slack, the web app, and the API. |
| `mermaid_trace` | string\|null | Mermaid diagram source for the vulnerability trace. `null` when Hacktron did not produce one. |
| `occurrence_count` | integer | Number of scans in which this finding has appeared. Minimum `1`. |
| `repo_url` | string\|null | Primary repository URL of the parent scan. |
| `scan_type` | enum\|null | `pr` or `full`. |

### Triage thread entry

| Field | Type | Description |
| ----------- | ------------- | ------------------------------------------------------------------------ |
| `id` | UUID | Entry identifier. |
| `reaction` | string\|null | Triage reaction. One of the finding states (`open`, `true_positive`, `false_positive`, `accepted_risk`, `resolved`). `null` for comment-only entries. |
| `comment` | string\|null | Comment text. `null` for reaction-only entries. |
| `user_id` | UUID | Author user ID. |
| `username` | string | Author display name. |
| `source` | enum | Origin of the entry. One of `github`, `slack`, `web`, `api`, `agent`. |
| `timestamp` | string | ISO 8601 timestamp. |

## Errors

- `404` — finding not found, still in verification, or not visible to your organization.
Loading