API reference

API documentation

Current product and API documentation for the SecPulse security intelligence platform.

Overview

SecPulse currently combines a signed-in operator workspace with a token-authenticated paygo tool API.

Intel hub with scan deltas, liveness analytics, hot findings, and graph entry points

Findings workflow with evidence uploads, notes, disclosure, and reuse graph pivots

Standalone binary file scanning and executable analysis

Repo scans that inspect both likely text files and common binary artifacts

Paygo tools billed against credits

AI chat with moderation, strike handling, and admin block controls

Authentication

SecPulse has two API surfaces:

/api/* for signed-in app users. These routes are intended for the web app and authenticated session flows.
/api/paygo/tools/* for token-authenticated pay-as-you-go tool runs billed against credits.

Generate API tokens from your API keys page. Include the token when calling the paygo tool API:

Authorization: Bearer sp_your_token_here

Tokens start with sp_ and are 67 characters long. They never expire unless you set an expiry. Session-backed routes use your signed-in browser session instead of this header.

Findings

These routes are part of the signed-in application API. They are intended for authenticated session use inside the SecPulse app.

GET/api/findingsAuth required

List findings with filters. Supports pagination, search, and filtering by status, severity, type, and source.

Response

{
  "findings": [...],
  "total": 301,
  "page": 1,
  "limit": 20
}

Example

curl --cookie "your_session_cookie_here" \
  "https://secpulse.tech/api/findings?status=submitted&severity=critical&search=aws&page=1&limit=20"

POST/api/findingsAuth required

Submit a new finding. Auto-deduplicates — if same repo+file+type exists, returns the existing finding with duplicate:true.

Request body

{
  "repoUrl": "https://github.com/owner/repo",
  "filePath": ".env",
  "secretType": "anthropic_api_key",
  "severity": "critical",
  "secretPrefix": "sk-ant-ap",
  "description": "API key committed to public repo"
}

Example

curl -X POST --cookie "your_session_cookie_here" \
  -H "Content-Type: application/json" \
  -d '{"repoUrl":"...","filePath":".env","secretType":"anthropic_api_key"}' \
  "https://secpulse.tech/api/findings"

GET/api/findings/:idAuth required

Get a single finding with notifications, status history, notes, evidence, key-check history, and generated intel.

Example

curl --cookie "your_session_cookie_here" "https://secpulse.tech/api/findings/abc123"

PATCH/api/findings/:idAuth required

Update finding status, severity, or description.

Request body

{
  "status": "validated",
  "severity": "critical"
}

Example

curl -X PATCH --cookie "your_session_cookie_here" \
  -H "Content-Type: application/json" \
  -d '{"status":"validated"}' "https://secpulse.tech/api/findings/abc123"

POST/api/findings/:id/notifyAuth required

Create a GitHub disclosure issue on the affected repo. Uses your GitHub OAuth token.

Response

{
  "issueUrl": "https://github.com/owner/repo/issues/1"
}

Example

curl -X POST --cookie "your_session_cookie_here" "https://secpulse.tech/api/findings/abc123/notify"

Scans

Scan routes are also session-backed and run in the context of your linked GitHub account.

POST/api/scansAuth required

Trigger a GitHub code search scan for leaked secrets.

Request body

{
  "patternIds": ["anthropic_api_key", "openai_api_key"],
  "maxResults": 20
}

Example

curl -X POST --cookie "your_session_cookie_here" \
  -H "Content-Type: application/json" \
  -d '{"maxResults":20}' "https://secpulse.tech/api/scans"

POST/api/scans/repoAuth required

Scan a specific repo for all secret patterns. Repo scans now inspect likely text files and extract printable strings from common binary artifacts.

Request body

{
  "repoUrl": "https://github.com/owner/repo"
}

Example

curl -X POST --cookie "your_session_cookie_here" \
  -H "Content-Type: application/json" \
  -d '{"repoUrl":"https://github.com/owner/repo"}' "https://secpulse.tech/api/scans/repo"

POST/api/scans/binaryAuth required

Upload and scan a local binary or encoded file. SecPulse extracts printable strings and runs the full secret detector set.

Response

{
  "scanId": "scan_123",
  "findings": 2,
  "fileName": "sample.bin"
}

Example

curl -X POST --cookie "your_session_cookie_here" \
  -F "file=@sample.bin" "https://secpulse.tech/api/scans/binary"

POST/api/scans/executableAuth required

Upload and analyze an executable. Returns file hashes, PE/ELF/Mach-O detection, extracted indicators, suspicious strings, and embedded-secret hits.

Response

{
  "scanId": "scan_123",
  "findings": 1,
  "fileName": "sample.exe",
  "analysis": {
    "format": "pe",
    "hashes": { "sha256": "..." },
    "score": { "value": 74, "label": "high-interest executable" }
  }
}

Example

curl -X POST --cookie "your_session_cookie_here" \
  -F "file=@sample.exe" "https://secpulse.tech/api/scans/executable"

GET/api/scans/:idAuth required

Get scan detail with current findings plus delta information against the previous comparable scan.

Example

curl --cookie "your_session_cookie_here" "https://secpulse.tech/api/scans/scan_123"

POST/api/scans/importAuth required

Bulk import findings from CSV format.

Request body

{
  "data": "owner/repo, .env, anthropic_api_key, critical"
}

Example

curl -X POST --cookie "your_session_cookie_here" \
  -H "Content-Type: application/json" \
  -d '{"data":"owner/repo, .env, anthropic_api_key, critical"}' "https://secpulse.tech/api/scans/import"

Evidence

Evidence is now a first-class workspace. Findings support notes, URLs, text artifacts, and binary uploads. The dedicated evidence index aggregates artifacts across the workspace.

GET/api/evidenceAuth required

List recent evidence artifacts with finding context.

Response

{
  "evidence": [
    {
      "id": "ev_123",
      "label": "proxy capture",
      "artifactType": "document",
      "findingId": "finding_123"
    }
  ]
}

Example

curl --cookie "your_session_cookie_here" "https://secpulse.tech/api/evidence"

POST/api/findings/:id/evidenceAuth required

Create a text, note, or URL evidence artifact on a finding.

Request body

{
  "label": "repro notes",
  "artifactType": "note",
  "content": "Observed reflected ACAO with arbitrary origin."
}

Example

curl -X POST --cookie "your_session_cookie_here" \
  -H "Content-Type: application/json" \
  -d '{"label":"repro notes","artifactType":"note","content":"..."}' "https://secpulse.tech/api/findings/abc123/evidence"

POST/api/findings/:id/evidence/uploadAuth required

Upload a binary evidence artifact. Supports images, PDFs, JSON, and text files.

Example

curl -X POST --cookie "your_session_cookie_here" \
  -F "file=@capture.pdf" \
  -F "label=packet capture" "https://secpulse.tech/api/findings/abc123/evidence/upload"

Paygo tools

Pay-as-you-go tools are called through a separate token-authenticated API surface. Each successful request charges credits using the tool's configured paygo price and returns billing metadata with the result.

POST/api/paygo/tools/header_analyzerAuth required

Run the header analyzer using an API token and paygo credits.

Request body

{
  "url": "https://example.com"
}

Response

{
  "url": "https://example.com",
  "headers": [...],
  "billing": {
    "actionId": "header_scan",
    "charged": 0.05,
    "balance": 12.45
  }
}

Example

curl -X POST -H "Authorization: Bearer sp_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}' "https://secpulse.tech/api/paygo/tools/header_analyzer"

POST/api/paygo/tools/cors_scannerAuth required

Run the CORS scanner with credits.

Request body

{
  "domain": "api.example.com",
  "paths": "/ /api /graphql"
}

Example

curl -X POST -H "Authorization: Bearer sp_xxx" \
  -H "Content-Type: application/json" \
  -d '{"domain":"api.example.com","paths":"/ /api /graphql"}' "https://secpulse.tech/api/paygo/tools/cors_scanner"

Notifications

GET/api/inboxAuth required

Get your in-app notifications with unread count.

Response

{
  "notifications": [...],
  "unread": 3
}

Example

curl -H "Authorization: Bearer sp_xxx" "https://secpulse.tech/api/inbox"

Assets

GET/api/assetsAuth required

List your monitored assets.

Example

curl -H "Authorization: Bearer sp_xxx" "https://secpulse.tech/api/assets"

POST/api/assetsAuth required

Add an asset to monitor.

Request body

{
  "assetType": "github_repo",
  "name": "owner/repo"
}

Example

curl -X POST -H "Authorization: Bearer sp_xxx" \
  -H "Content-Type: application/json" \
  -d '{"assetType":"github_repo","name":"owner/repo"}' "https://secpulse.tech/api/assets"

Alerts

POST/api/alertsAuth required

Create an alert rule.

Request body

{
  "name": "Critical AWS keys",
  "conditions": "{\"severity\":\"critical\",\"secretType\":\"aws_access_key\"}"
}

Example

curl -X POST -H "Authorization: Bearer sp_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"Critical AWS","conditions":"{}"}' "https://secpulse.tech/api/alerts"

Integrations

POST/api/integrationsAuth required

Add a webhook integration (Slack, Discord, or generic).

Request body

{
  "type": "discord",
  "name": "my discord",
  "config": "{\"webhookUrl\":\"https://discord.com/api/webhooks/...\"}",
  "events": ["new_finding", "finding_remediated"],
  "severityFilter": "high"
}

Example

curl -X POST -H "Authorization: Bearer sp_xxx" \
  -H "Content-Type: application/json" \
  -d '{"type":"slack","name":"alerts","config":"{\"webhookUrl\":\"...\"}"}' "https://secpulse.tech/api/integrations"

AI chat

POST/api/chatAuth required

Send a message to SecPulse AI. The assistant has workspace context across findings, assets, and scans. The chat flow also includes moderation, jailbreak detection, and admin-enforced blocks.

Request body

{
  "message": "what should I prioritize?",
  "sessionId": "chat_123"
}

Response

{
  "response": "Hey! You have 301 findings...",
  "sessionId": "chat_123"
}

Example

curl -X POST -H "Authorization: Bearer sp_xxx" \
  -H "Content-Type: application/json" \
  -d '{"message":"summarize my findings"}' "https://secpulse.tech/api/chat"

Search

GET/api/search?q=keywordAuth required

Search across findings, users, assets, and scans.

Response

{
  "findings": [...],
  "users": [...],
  "assets": [...],
  "scans": [...]
}

Example

curl -H "Authorization: Bearer sp_xxx" "https://secpulse.tech/api/search?q=aws+key"

Statistics

GET/api/statsPublic

Platform-wide stats: totals, breakdowns, posture, liveness analytics, deltas, and hot findings.

Response

{
  "totals": { "total": 301, "remediated": 0, "notified": 79 },
  "bySeverity": [...],
  "bySource": [...],
  "posture": {...},
  "liveness": {...},
  "deltas": {...},
  "hotFindings": [...]
}

Example

curl "https://secpulse.tech/api/stats"

Export

GET/api/export?format=csvAuth required

Export your findings as CSV or JSON.

Example

curl -H "Authorization: Bearer sp_xxx" "https://secpulse.tech/api/export?format=csv" -o findings.csv

Health & feed

GET/api/healthPublic

Platform health check.

Example

curl "https://secpulse.tech/api/health"

GET/api/feedPublic

RSS/Atom feed of platform activity.

Example

curl "https://secpulse.tech/api/feed"

Webhook events

Configure which events trigger your webhooks in Settings. Supported events:

new_finding

A new finding is submitted

finding_notified

A repo owner is notified via GitHub issue

finding_remediated

A finding is confirmed remediated

finding_status_changed

Any status change on a finding

scan_completed

A scan finishes (manual or scheduled)

comment_added

A comment is added to a finding

alert_triggered

An alert rule matches a new finding

You can also filter by minimum severity per integration (all, low, medium, high, critical).

Rate limits

Requests/hour

1,000

Findings/day

Scans/hour

Need higher limits? Contact support.

Automated schedules

These run automatically — no action needed.

GitHub secret scan

Searches GitHub for new leaked keys across top patterns

Daily · 00:00 UTC

Dark web scan

Searches dark web sources for watchlist keywords

Daily · 03:00 UTC

Remediation check

Re-checks notified findings, auto-marks remediated

Daily · 06:00 UTC

Asset monitor

Scans all monitored repos and orgs

Daily · 08:00 UTC

Paste site scan

Checks paste sites for your monitored keywords

Daily · 12:00 UTC

Exact cadence depends on deployment and plan. The current codebase supports scheduled repo, remediation, paste, monitor, and dark web jobs plus richer per-scan delta views in the app.