# Quick Start
This page walks you through the basics of using Takumi API—from setup to retrieving results—using whitebox assessment as an example.
The core flow (uploading files, running a workflow, and retrieving results) is common across all workflows, so this guide applies to other workflows as well.
## Overview
An API-driven assessment follows roughly this communication flow:
```mermaid
sequenceDiagram
participant User as API Consumer
participant API as Takumi API
User->>API: Upload input files
API-->>User: file_id
User->>API: Run workflow
API-->>User: workflow_run_id
Note over API: Takumi runs the assessment
(hours to days)
API-)User: Notify completion via webhook
User->>API: Retrieve results & artifacts
API-->>User: Assessment results, reports, etc.
```
:::note
You can also poll the status API instead of using webhooks. However, if you're running in an environment that charges by execution time (such as GitHub Actions), consider splitting the process into two parts: one that dispatches the workflow and exits immediately, and another that is triggered by the webhook to process the results. This minimizes the time your execution environment stays running.
:::
## Setup
### Get an Access Token
Takumi API supports authentication both as a user and as a **bot**—a non-person entity. For CI/CD pipelines and other automated contexts not tied to a specific user, bot authentication is recommended. Some OIDC-compatible environments support short-lived credentials; alternatively, you can issue a long-lived API key.
You can obtain an access token using one of the following methods. For details, see [Accessing via shishoctl CLI](https://shisho.dev/docs/c/accessing-via-shishoctl-cli/).
- **Authenticate as a user**: Sign in with `shishoctl auth signin`, then retrieve a token with `shishoctl auth print-access-token`
- **Authenticate as a bot**: Sign in with `shishoctl auth signin:bot`, then retrieve a token with `shishoctl auth print-access-token`
Include the token in all subsequent API requests:
```
Authorization: Bearer {ACCESS_TOKEN}
```
### Configure a Webhook
Set up a webhook to receive notifications when a workflow completes. For step-by-step instructions, see [Webhook Notifications](/docs/t/api/features/webhook.md).
This setup is not required if you plan to poll for workflow completion instead.
### Verify Ownership of the Target Application (Some Workflows Only)
Features that communicate dynamically with a live environment (including blackbox assessment) can only target applications you own. If you specify an unverified application URL as the assessment target, the workflow will be rejected.
Complete the ownership verification process as described in [Organization Verification and Ownership Verification](/docs/t/concepts/assessment-authentication.md).
Whitebox assessment does not involve dynamic communication with a live environment, so this restriction does not apply.
## Understand Workflow Inputs and Outputs
The input and output schemas differ by workflow type and are defined in the [OpenAPI documentation](https://api.cloud.shisho.dev/v1/docs/openapi.json).
The workflow ID for whitebox assessment is `whitebox-assessment`, and its API endpoints are under `/o/{org_id}/workflows/whitebox-assessment/*`.
Here is a partial excerpt of the request schema for the workflow dispatch endpoint `/o/{org_id}/workflows/whitebox-assessment/dispatch`. From this schema, you can see:
- The target codebase must be uploaded in advance via the `/o/{org_id}/input-files` API. Specify the resulting file ID in `input.targets[].file_upload.file_id`. Supported archive formats are ZIP and tar.gz.
- Specify the output language for the assessment report in `input.language`.
```yaml
/o/{org_id}/workflows/whitebox-assessment/dispatch:
post:
requestBody:
content:
application/json:
schema:
properties:
input:
properties:
# Target codebases for assessment
targets:
description: Source code archives to analyze
type: array
items:
properties:
file_upload:
properties:
description: Source code archive uploaded via the input files API
file_id: { type: string }
archive_type:
enum: [zip, tar_gz]
# Language for the assessment report
language:
enum: [english, japanese]
# ... (see OpenAPI documentation for other parameters)
notification:
description: Optional notification configuration for the workflow run
properties:
# Webhook endpoint to notify on workflow completion
webhook_endpoint_ids:
type: array
items: { type: string }
```
Next, let's look at the output schema. Once a workflow completes, you can retrieve its results from the `/o/{org_id}/workflows/{workflow_id}/describe` endpoint. Here is a partial excerpt of the response schema for `/o/{org_id}/workflows/whitebox-assessment/describe`:
```yaml
/o/{org_id}/workflows/whitebox-assessment/describe:
post:
responses:
"200":
content:
application/json:
schema:
properties:
status:
description: Current status of the workflow run
enum: [RUNNING, EXITED]
artifacts:
description: Downloadable artifacts produced by the workflow run. Present only when status is EXITED
type: array
items:
properties:
name: { type: string }
output:
description: Output of the workflow run. Present only when status is EXITED
properties:
kind:
description: Whether the workflow run succeeded or was aborted
enum: [SUCCESS, ABORTED]
successOutput:
description: The success output. Present only when kind is SUCCESS
properties:
findings:
description: A JSON file containing the list of vulnerability findings. The schema is available at `/v1/docs/workflow-artifacts/whitebox-assessment/findings.json`
properties:
artifact_name: { type: string }
type: object
report:
description: The assessment report in Markdown format
properties:
artifact_name:
type: string
type: object
type: object
abortedReason:
description: The reason the workflow run was aborted. Present only when kind is ABORTED
properties: # ... (omitted)
```
From this, you can see the artifacts produced when a whitebox assessment succeeds:
- `report`: The assessment report in Markdown format
- `findings`: A JSON file containing the list of detected vulnerabilities. The JSON Schema is available at `https://api.cloud.shisho.dev/v1/docs/workflow-artifacts/whitebox-assessment/findings.json`
Let's now walk through running a workflow.
## Run a Workflow
### Step 1: Upload Input Files
Whitebox assessment requires uploading the target codebase as a ZIP or tar.gz archive, then specifying the file ID as workflow input. If the workflow doesn't require file input (such as blackbox assessment), skip this step.
For details on how file upload works, see [File Upload](/docs/t/api/features/file-upload.md).
#### Get an Upload URL
First, specify the file size in bytes to obtain an upload URL.
```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
https://api.cloud.shisho.dev/v1/o/$org_id/input-files/get-upload-url \
--json '{"content_length": 123456}'
```
On success, the response includes a `file_id` (the file identifier) and an `upload_url` (a temporary URL for upload).
```json
{
"file_id": "TIF...",
"upload_url": "https://..."
}
```
#### Upload the File
Upload your source code archive to the `upload_url` via HTTP PUT. No `Authorization` header is required for this request.
```bash
curl -s -X PUT "" --upload-file ./your-project.zip
```
#### Confirm the Upload
After uploading, call the confirm-upload API. The file is not available as workflow input until this step completes.
```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
https://api.cloud.shisho.dev/v1/o/$org_id/input-files/confirm-upload \
--json '{"file_id": "TIF..."}'
```
:::note
If you decide not to complete the upload, call `/o/{org_id}/input-files/cancel-upload` to cancel it. This ensures the cancelled upload is correctly reflected in your storage usage.
:::
### Step 2: Run the Workflow
Call the workflow dispatch API to start the assessment.
Specify the webhook endpoint ID you registered during setup in `notification.webhook_endpoint_ids` to receive a notification when the workflow completes.
```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
https://api.cloud.shisho.dev/v1/o/$org_id/workflows/whitebox-assessment/dispatch \
--json '{
"input": {
"language": "english",
"targets": [
{
"file_upload": {
"file_id": "TIF...",
"archive_type": "zip"
}
}
]
},
"notification": {
"webhook_endpoint_ids": ["WH..."]
}
}'
```
The input format varies by workflow type. For details, refer to the request schema for each endpoint in the [OpenAPI documentation](https://api.cloud.shisho.dev/v1/docs/openapi.json).
On success, the response includes the `workflow_run_id`.
```json
{
"workflow_run_id": "TWR..."
}
```
:::note
Workflows can take anywhere from a few hours to a few days to complete, depending on the size and complexity of the application.
:::
To cancel a running workflow, call the `/o/{org_id}/workflows/{workflow_id}/cancel` endpoint.
### Step 3: Receive the Completion Notification
When the workflow completes, Takumi sends a notification to your webhook endpoint. For details on webhook notifications, see [Webhook Notifications](/docs/t/api/features/webhook.md).
```json
{
"type": "api.workflow_run.exited",
"timestamp": "2024-01-01T00:00:00Z",
"data": {
"workflow_id": "whitebox-assessment",
"workflow_run_id": "TWR..."
}
}
```
Use `data.workflow_run_id` to identify the workflow run, then proceed to the next step to retrieve the results.
If you prefer polling over webhooks, you can check the run status from the `/o/{org_id}/workflows/{workflow_id}/describe` endpoint:
```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
https://api.cloud.shisho.dev/v1/o/$org_id/workflows/whitebox-assessment/describe \
--json '{"workflow_run_id": "TWR..."}'
```
### Step 4: Retrieve Results
Once the workflow has completed, call `/o/{org_id}/workflows/{workflow_id}/describe` to fetch the results.
If `output.kind` is `"SUCCESS"`, the assessment succeeded. The response also includes a list of artifacts.
```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
https://api.cloud.shisho.dev/v1/o/$org_id/workflows/whitebox-assessment/describe \
--json '{"workflow_run_id": "TWR..."}'
```
The result format varies by workflow type. For details, refer to the response schema for each endpoint in the [OpenAPI documentation](https://api.cloud.shisho.dev/v1/docs/openapi.json). The schema also describes the content and format of each artifact.
For example, the response schema for `/o/{org_id}/workflows/whitebox-assessment/describe` defines the following:
```yaml
successOutput:
properties:
findings:
description: A JSON file containing the list of vulnerability findings. The schema is available at `/v1/docs/workflow-artifacts/whitebox-assessment/findings.json`
properties:
artifact_name: { type: string }
report:
description: The assessment report in Markdown format
properties:
artifact_name: { type: string }
```
To download an artifact, call `/o/{org_id}/workflows/{workflow_id}/get-artifact-download-url` to obtain a download URL. For example, to download the assessment report (`report`) from a whitebox assessment:
```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
https://api.cloud.shisho.dev/v1/o/$org_id/workflows/whitebox-assessment/get-artifact-download-url \
--json '{
"workflow_run_id": "TWR...",
"artifact_name": "report"
}'
```
Download the artifact via HTTP GET using the `url` from the response:
```bash
curl -s -o report.md ""
```
:::note
Workflow results and artifacts are retained for a minimum of 30 days, but may be deleted after that. If you need to keep results long-term, we recommend downloading them promptly.
:::
## Next Steps
You've now completed the basic flow for running a whitebox assessment via Takumi API. Now that you have the fundamentals down, here are some ways to take it further:
- **CI/CD integration**: Embed Takumi in a GitHub Actions pipeline to automatically trigger assessments after deployment
- **Ticket management integration**: Automatically create GitHub Issues or Jira tickets based on assessment findings
- **Other workflows**: Explore other workflows available through Takumi API, such as blackbox assessment