API docs by Redocly

Shinobi Public API (1.0.0)

Download OpenAPI specification:

Shinobi Security: support@shinobi.security URL: https://shinobi.security

Programmatic access to security findings and project data.

Authentication

Pass your API token in the Authorization header:

curl -H "Authorization: Bearer sh_live_k9s8d_9f8s7d6f5..." \
  https://service.shinobi.security/v1/projects/{projectId}/findings

Token format: sh_<env>_<id>_<secret>

  • sh - Shinobi prefix (helps secret scanners detect leaked tokens)
  • env - Environment: live (production) or test (sandbox)
  • id - Public key identifier (safe to log)
  • secret - Secret part (never log this)

All major HTTP libraries support Bearer tokens:

# Python requests
requests.get(url, headers={"Authorization": "Bearer sh_live_..."})

// Node.js axios
axios.get(url, { headers: { Authorization: "Bearer sh_live_..." } })

Rate Limits

  • 50 requests/second (burst)
  • 50,000 requests/month

Pagination

This API uses cursor-based pagination for consistent results:

{
  "data": [...],
  "cursor": "eyJ0ZW5hbnQiOiJ...",
  "hasMore": true
}

Pass the cursor value in subsequent requests to fetch the next page.

Filtering

Use query parameters to filter results server-side:

  • severity: Comma-separated severity levels (e.g., CRITICAL,HIGH)
  • status: Comma-separated statuses (e.g., OPEN,IN_PROGRESS)
  • since: ISO-8601 timestamp for incremental sync - returns findings updated after this time (e.g., 2024-01-01T00:00:00Z)

Projects

List projects

Returns a paginated list of projects accessible by the API token.

Required Scope: project:view (enabled by default on all keys)

Results are sorted by creation time (newest first).

Authorizations:
ApiKeyAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 100

Items per page (1-100, default 100)

cursor
string

Pagination cursor from previous response.

name
string
Example: name=Payment

Filter by project name (case-insensitive contains match)

createdAfter
string <date-time>
Example: createdAfter=2024-01-01T00:00:00Z

Filter projects created after this ISO-8601 timestamp

createdBefore
string <date-time>
Example: createdBefore=2024-12-31T23:59:59Z

Filter projects created before this ISO-8601 timestamp

status
string
Enum: "PENDING" "IN_PROGRESS" "PAUSED" "COMPLETED"

Filter by latest run status

stage
string
Enum: "Scoping" "Exploring" "Creating Attack Scenarios" "Awaiting Test Start" "Testing" "Reporting" "Completed"

Filter by current stage (milestone)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "cursor": "string",
  • "hasMore": true
}

Get project

Returns details for a single project.

Required Scope: project:view (enabled by default on all keys)

Authorizations:
ApiKeyAuth
path Parameters
projectId
required
string^[A-Za-z0-9_-]{21}$|^[0-9a-f]{8}-[0-9a-f]{4}-...

Project identifier (21-char nanoid or UUID format)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Findings

List findings

Returns a paginated list of findings for a project.

Use the view parameter to control response detail:

  • summary (default): Returns core fields only (id, title, severity, status, timestamps)
  • full: Returns all available fields including CVSS details and remediation (slower, lower limits)

Results are sorted by creation time (createdAt). Use sort=desc for newest first.

Authorizations:
ApiKeyAuth
path Parameters
projectId
required
string^[A-Za-z0-9_-]{21}$|^[0-9a-f]{8}-[0-9a-f]{4}-...

Project identifier (21-char nanoid or UUID format)

query Parameters
view
string
Default: "summary"
Enum: "summary" "full"

Data density. summary returns basic fields, full includes all details.

severity
string
Example: severity=CRITICAL,HIGH

Filter by severity. Comma-separated values.

status
string
Example: status=OPEN,RETESTING

Filter by status. Comma-separated values.

since
string <date-time>
Example: since=2024-01-01T00:00:00Z

Return findings updated (modified) after this ISO-8601 timestamp. Useful for incremental sync - captures both new findings and status changes.

sort
string
Default: "asc"
Enum: "asc" "desc"

Sort direction by creation time.

cursor
string

Pagination cursor from previous response.

limit
integer [ 1 .. 100 ]
Default: 50

Items per page. Max 100 for summary view, 25 for full view.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "cursor": "string",
  • "hasMore": true
}

Get finding

Returns full details for a single finding including CVSS information, remediation steps, and affected endpoints.

Authorizations:
ApiKeyAuth
path Parameters
projectId
required
string^[A-Za-z0-9_-]{21}$|^[0-9a-f]{8}-[0-9a-f]{4}-...

Project identifier (21-char nanoid or UUID format)

findingId
required
string^[A-Za-z0-9_-]{10,50}$

Finding identifier

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}