Shinobi Public API (1.0.0)

Download OpenAPI specification:

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
}

Search projects

Returns the requested projects (1–100) in one call, with filters and cursor pagination.

Access is all-or-nothing: if any ID is not accessible (not in the key's project list, another organization's project, deleted, or not found), the whole request is rejected with 403 and details.rejectedProjectIds. Projects excluded by filters are simply not returned (not an error). To list every accessible project, use GET /projects.

Results are sorted by creation time (sort.order, default desc). The cursor is opaque; send it back unchanged with the same request body to get the next page.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
projectIds
required
Array of strings [ 1 .. 100 ] items

Projects to return (all-or-nothing access)

object
object
limit
integer [ 1 .. 100 ]
Default: 100
cursor
string

Opaque cursor from the previous response

Responses

Request samples

Content type
application/json
{
  • "projectIds": [
    ],
  • "filters": {
    },
  • "sort": {
    },
  • "limit": 100
}

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

Search findings

Returns approved findings across up to 100 projects in one call, merged into a single list sorted by creation time (sort.order, default asc).

Each entry in projects may list findingIds; without them, all of that project's findings are searched. Filters apply to listed findings too.

Access is all-or-nothing: if any project or listed finding is not accessible or not found, the whole request is rejected with 403 and details.rejectedProjectIds / details.rejectedFindings. Projects excluded by tags / types are simply not returned (not an error).

Pagination: a page can contain fewer than limit results — even zero — while hasMore is true (each request reads a bounded number of findings, so very selective filters on large projects may need several requests). Keep following cursor until hasMore is false. The cursor is opaque; send it back unchanged with the same request body.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
required
Array of objects [ 1 .. 100 ] items

Projects to search; each projectId at most once. At most 100 finding IDs in total.

object
object
view
string
Default: "summary"
Enum: "summary" "full"
limit
integer [ 1 .. 100 ]
Default: 50

Max 25 for view=full

cursor
string

Opaque cursor from the previous response

Responses

Request samples

Content type
application/json
{
  • "projects": [
    ],
  • "filters": {
    },
  • "limit": 50
}

Response samples

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

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

Custom Attacks

Create custom attack

Creates a user-defined custom attack on the project's current test run. By default the attack is queued for execution immediately; send start: false to create it without queueing.

This describes a test scenario for Shinobi to run (title, goal, target). It does not accept or execute custom code.

Requirements:

  • The project must have a test run that has reached the testing phase (Testing, Reporting or Completed). Adding an attack moves the run back to Testing.
  • target must be within the project's configured scope.
  • Each created attack counts towards the organisation's mission limit.

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
title
required
string <= 150 characters

Short name for the attack

goal
required
string <= 7000 characters

What the attack should try to achieve or verify

target
required
string

Target URL, or a JSON-encoded array of URLs, to attack. Every target must be within the project's configured scope.

supportingInformation
string

Optional extra context for the attack

start
boolean
Default: true

Queue the attack for execution immediately. Set to false to create it without queueing.

Responses

Request samples

Content type
application/json
Example
{
  • "title": "IDOR on order history",
  • "goal": "Check whether a user can read another user's orders by changing the order ID",
  • "supportingInformation": "Order IDs are sequential integers"
}

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
}