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": {
    }
}

Trigger

Trigger test

Triggers a CI-initiated test run on a whitebox project.

The project must be whitebox (at least one repository configured), otherwise the request is rejected with NOT_WHITEBOX. Mobile projects are also supported and may optionally supply an apkUrl (HTTPS) to a fresh build — Shinobi securely downloads it, stores it against the project, and tests that build. When omitted, the project's current APK is tested.

At least one of repositories (scopes the test per repository to a PR, commit, or range) or releaseNotes (a free-text description of what changed) is required for whitebox (repository-backed) projects. Projects without repositories must provide releaseNotes.

A project can have several repositories linked. Each repositories entry names a repository that is linked to the project and optionally carries a diff describing what changed in it. Repositories you leave out — or leave without a diff — are tested in full at their configured branch, so you only send change context for the repos that actually changed.

Only repoFullName and diff are accepted. The repository's connection, organisation and branches are always taken from the project's own configuration and are echoed back on the response.

Required Scope: trigger:write

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)

Request Body schema: application/json
required
Array of objects (TriggerTestRepository) <= 50 items

The repositories that changed, each with an optional diff. At most one entry per repository, and each repoFullName must be a repository linked to this project. Repositories you omit — or leave without a diff — are tested in full at their configured branch.

releaseNotes
string [ 1 .. 10000 ] characters

Free-text description of changes being tested. Whitebox projects need this or a scoped repositories entry (at least one); required for projects without repositories.

apkUrl
string <uri> <= 2048 characters

Mobile projects only. HTTPS URL to a fresh APK/APKS/XAPK build. Shinobi securely downloads the build, stores it against the project, and tests it. Omit to test the project's current APK. Rejected for non-mobile projects.

Responses

Request samples

Content type
application/json
Example
{
  • "releaseNotes": "Fixed auth redirect handling",
  • "repositories": [
    ]
}

Response samples

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

Audit Logs

List audit logs

Returns a paginated list of tenant-wide audit log events.

Includes project-level, org-level, and system access events. Use the tenant, project, and access category params to include or exclude each category independently.

Required Scope: audit-logs:read Required Key Type: All-projects key (allProjects: true)

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

Items per page (1-200, default 100)

cursor
string

Pagination cursor from previous response.

from
integer
Example: from=1716300000000

Start of time range (epoch milliseconds)

to
integer
Example: to=1716400000000

End of time range (epoch milliseconds)

taskId
string

Filter by project ID. Repeatable (max 50). Implies project=include.

userId
string

Filter by user principal ID. Repeatable (max 50).

tenant
string
Default: "include"
Enum: "include" "exclude"

Include or exclude org-level events (default include)

project
string
Default: "include"
Enum: "include" "exclude"

Include or exclude project-scoped events (default include)

access
string
Default: "include"
Enum: "include" "exclude"

Include or exclude system access events like login/logout (default include)

Responses

Response samples

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