{ "components": { "parameters": { "orgID": { "in": "path", "name": "orgID", "required": true, "schema": { "type": "string" } } } }, "info": { "title": "Takumi API", "version": "v1" }, "openapi": "3.1.0", "paths": { "/o/{orgID}/input-files/cancel-upload": { "post": { "parameters": [ { "$ref": "#/components/parameters/orgID" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "file_id": { "type": "string", "maxLength": 256, "minLength": 1, "description": "The ID of the file upload to cancel" } }, "additionalProperties": false, "type": "object", "required": [ "file_id" ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "file_id": { "type": "string", "description": "The ID of the canceled file" } }, "type": "object", "required": [ "file_id" ] } } }, "description": "Successful response" } }, "summary": "Cancel a pending file upload" } }, "/o/{orgID}/input-files/confirm-upload": { "post": { "parameters": [ { "$ref": "#/components/parameters/orgID" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "file_id": { "type": "string", "maxLength": 256, "minLength": 1, "description": "The ID of the file to confirm. Must call this after uploading the file to the upload URL" } }, "additionalProperties": false, "type": "object", "required": [ "file_id" ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "file_id": { "type": "string", "description": "The ID of the confirmed file" } }, "type": "object", "required": [ "file_id" ] } } }, "description": "Successful response" } }, "summary": "Confirm a file upload" } }, "/o/{orgID}/input-files/delete": { "post": { "parameters": [ { "$ref": "#/components/parameters/orgID" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "file_id": { "type": "string", "maxLength": 256, "minLength": 1, "description": "The ID of the file to delete" } }, "additionalProperties": false, "type": "object", "required": [ "file_id" ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "file_id": { "type": "string", "description": "The ID of the deleted file" } }, "type": "object", "required": [ "file_id" ] } } }, "description": "Successful response" } }, "summary": "Delete a file" } }, "/o/{orgID}/input-files/get-upload-url": { "post": { "description": "Returns a URL for uploading a file via HTTP PUT.\n\n```\ncurl -X PUT \"\u003cupload_url\u003e\" --upload-file path/to/file\n```\n\nAfter the upload completes, call `/input-files/confirm-upload` to finalize the file. The file can only be referenced in workflow inputs after confirmation.\n\nUploaded files are automatically deleted after a retention period. Storage capacity is limited per organization. Delete files that are no longer needed using the `/input-files/delete` endpoint.\n\nTo abort an upload, call `/input-files/cancel-upload` so that the reserved storage capacity is released.", "parameters": [ { "$ref": "#/components/parameters/orgID" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "content_length": { "type": "integer", "minimum": 1, "description": "Size of the file to upload in bytes" } }, "additionalProperties": false, "type": "object", "required": [ "content_length" ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "file_id": { "type": "string", "description": "The ID assigned to this file. Use this ID in subsequent confirm/cancel calls and in workflow dispatch inputs" }, "upload_url": { "type": "string", "description": "URL to upload the file via HTTP PUT" }, "expires_in_seconds": { "type": "integer", "description": "Number of seconds until the upload URL expires" } }, "type": "object", "required": [ "file_id", "upload_url", "expires_in_seconds" ] } } }, "description": "Successful response" } }, "summary": "Get an upload URL" } }, "/o/{orgID}/workflows/blackbox-assessment/cancel": { "post": { "parameters": [ { "$ref": "#/components/parameters/orgID" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "workflow_run_id": { "type": "string", "maxLength": 256, "minLength": 1, "description": "The ID of the workflow run to cancel" } }, "additionalProperties": false, "type": "object", "required": [ "workflow_run_id" ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": {}, "type": "object" } } }, "description": "Successful response" } }, "summary": "Cancel a blackbox-assessment workflow run" } }, "/o/{orgID}/workflows/blackbox-assessment/describe": { "post": { "description": "To download the artifacts listed in the response, use the `/blackbox-assessment/get-artifact-download-url` endpoint.", "parameters": [ { "$ref": "#/components/parameters/orgID" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "workflow_run_id": { "type": "string", "maxLength": 256, "minLength": 1, "description": "The ID of the workflow run to describe" } }, "additionalProperties": false, "type": "object", "required": [ "workflow_run_id" ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "enum": [ "RUNNING", "EXITED" ], "title": "Status", "description": "Current status of the workflow run" }, "output": { "properties": { "kind": { "type": "string", "enum": [ "SUCCESS", "ABORTED" ], "description": "Whether the workflow run succeeded or was aborted" }, "successOutput": { "properties": { "report": { "properties": { "artifact_name": { "type": "string", "description": "The name of the artifact" } }, "type": "object", "required": [ "artifact_name" ], "description": "The assessment report in Markdown format" }, "findings": { "properties": { "artifact_name": { "type": "string", "description": "The name of the artifact" } }, "type": "object", "required": [ "artifact_name" ], "description": "A JSON file containing the list of vulnerability findings. The schema is available at `/v1/docs/workflow-artifacts/blackbox-assessment/findings.json`" }, "features": { "properties": { "artifact_name": { "type": "string", "description": "The name of the artifact" } }, "type": "object", "required": [ "artifact_name" ], "description": "A JSON file containing the list of application features examined during the assessment. The schema is available at `/v1/docs/workflow-artifacts/blackbox-assessment/features.json`. Always present for runs created after this field was introduced; absent for older runs. Added in https://shisho.dev/docs/r/202603-takumi-api-scoped-blackbox-assessment" }, "scan_progress": { "properties": { "artifact_name": { "type": "string", "description": "The name of the artifact" } }, "type": "object", "required": [ "artifact_name" ], "description": "A JSON file containing the completed and skipped feature–perspective pairs. Completed pairs were actually tested; skipped pairs were not applicable (e.g. authentication perspective on a non-authentication feature). Pairs absent from both lists were not tested due to credit limit or other runtime constraints. The schema is available at `/v1/docs/workflow-artifacts/blackbox-assessment/scan_progress.json`. Always present for runs created after this field was introduced; absent for older runs. Added in https://shisho.dev/docs/r/202603-takumi-api-scoped-blackbox-assessment" } }, "type": "object", "required": [ "report", "findings" ], "description": "The success output. Present only when kind is SUCCESS" }, "abortedReason": { "properties": { "code": { "type": "string", "description": "The abort reason code" }, "detail": { "description": "Type-specific detail for the abort reason" } }, "type": "object", "required": [ "code" ], "description": "The reason the workflow run was aborted. Present only when kind is ABORTED" } }, "type": "object", "required": [ "kind" ], "description": "Output of the workflow run. Present only when status is EXITED" }, "artifacts": { "items": { "properties": { "name": { "type": "string", "description": "Name of the artifact" } }, "type": "object", "required": [ "name" ] }, "type": "array", "description": "Downloadable artifacts produced by the workflow run. Present only when status is EXITED" } }, "type": "object", "required": [ "status" ] } } }, "description": "Successful response" } }, "summary": "Describe a blackbox-assessment workflow run" } }, "/o/{orgID}/workflows/blackbox-assessment/dispatch": { "post": { "description": "Dispatches a blackbox assessment and returns immediately. Poll the `/blackbox-assessment/describe` endpoint to check status. Depending on the complexity of the target application, execution may take anywhere from several hours to several days.", "parameters": [ { "$ref": "#/components/parameters/orgID" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "input": { "properties": { "language": { "type": "string", "enum": [ "english", "japanese" ] }, "target_urls": { "items": { "type": "string", "maxLength": 5000, "format": "uri", "description": "A fully qualified URL (e.g. https://app.example)" }, "type": "array", "maxItems": 100, "minItems": 1, "description": "Web application URLs to test. Each URL must belong to an application whose ownership has been verified; otherwise the workflow run will be rejected. When 'resume' is specified; this must contain the same URLs as the referenced run. See https://shisho.dev/docs/t/concepts/assessment-authentication/ for setup instructions" }, "oos_urls": { "items": { "type": "string", "maxLength": 5000, "format": "uri", "description": "A fully qualified URL (e.g. https://app.example)" }, "type": "array", "maxItems": 100, "description": "Out-of-scope URLs to exclude from testing" }, "authentication": { "properties": { "credentials": { "items": { "properties": { "id": { "type": "string", "maxLength": 256, "minLength": 1, "description": "Login ID such as a username or email address" }, "password": { "type": "string", "maxLength": 5000, "description": "Login password" }, "role": { "type": "string", "maxLength": 256, "minLength": 1, "description": "Role label for this credential (e.g. \"admin\" or \"regular user\")" } }, "additionalProperties": false, "type": "object", "required": [ "id", "password", "role" ] }, "type": "array", "maxItems": 100, "minItems": 1, "description": "Login credentials for authenticated testing" }, "additional_instructions": { "type": "string", "maxLength": 5000, "minLength": 1, "description": "Additional instructions for the authentication process (e.g. login page URL; MFA setup steps)" } }, "additionalProperties": false, "type": "object", "description": "Credentials and instructions for logging into the target web application" }, "preference": { "properties": { "preferences": { "items": { "properties": { "kind": { "type": "string", "enum": [ "DO", "DONT" ], "description": "DO for a positive instruction; DONT for a negative instruction" }, "preference": { "type": "string", "maxLength": 5000, "minLength": 1, "description": "The instruction text (e.g. \"Please check the authentication feature\" for DO; \"No need to check the logging feature\" for DONT)" } }, "additionalProperties": false, "type": "object", "required": [ "kind", "preference" ] }, "type": "array", "maxItems": 100, "minItems": 1, "description": "Custom instructions to guide the assessment behavior. Note: Takumi does not always follow these instructions" } }, "additionalProperties": false, "type": "object", "description": "Custom instructions to guide the assessment. Note: Takumi does not always follow these instructions" }, "scan_credit_limit": { "type": "integer", "maximum": 100000, "minimum": 10, "description": "Maximum number of credits to consume while scanning. The assessment stops early and exits as ABORTED with code 'credit_limit_reached' when the limit is reached. The aborted reason detail includes a scan_progress artifact that records which pairs were completed or skipped; pairs absent from scan_progress were not attempted due to the limit and can be retried via 'resume.continue_assessment'" }, "crawl_credit_limit": { "type": "integer", "maximum": 100000, "minimum": 5, "description": "Maximum number of credits to consume while crawling. When the limit is reached; the scan proceeds with the features discovered so far. Independent of 'scan_credit_limit' which governs scanning" }, "resume": { "properties": { "kind": { "type": "string", "enum": [ "assess_crawled_features", "continue_assessment" ], "description": "Resume mode: 'assess_crawled_features' or 'continue_assessment'. Set the corresponding sub-object accordingly" }, "assess_crawled_features": { "properties": { "workflow_id": { "type": "string", "maxLength": 256, "minLength": 1, "description": "The ID of the workflow that produced the referenced run" }, "workflow_run_id": { "type": "string", "maxLength": 256, "minLength": 1, "description": "The ID of the workflow run to reference. The referenced run must have completed with SUCCESS or been ABORTED with code 'credit_limit_reached'; other abort reasons are not eligible" } }, "additionalProperties": false, "type": "object", "required": [ "workflow_id", "workflow_run_id" ], "description": "Required when kind is 'assess_crawled_features'. Reuse only the discovered feature list from a previous run and start a fresh assessment from scratch. The referenced run can be either a blackbox-assessment or a blackbox-crawl run" }, "continue_assessment": { "properties": { "workflow_id": { "type": "string", "maxLength": 256, "minLength": 1, "description": "The ID of the workflow that produced the referenced run" }, "workflow_run_id": { "type": "string", "maxLength": 256, "minLength": 1, "description": "The ID of the workflow run to reference. The referenced run must have completed with SUCCESS or been ABORTED with code 'credit_limit_reached'; other abort reasons are not eligible" } }, "additionalProperties": false, "type": "object", "required": [ "workflow_id", "workflow_run_id" ], "description": "Required when kind is 'continue_assessment'. Continue a previous blackbox-assessment run; reusing its feature list and scan results. New findings are appended to the previous report. The referenced run must be a blackbox-assessment run" } }, "additionalProperties": false, "type": "object", "required": [ "kind" ], "description": "Configuration for resuming from a previous workflow run. Set 'kind' to select the resume mode and populate the corresponding sub-object. The referenced run must have completed with SUCCESS or been ABORTED with code 'credit_limit_reached'" }, "pairs": { "items": { "properties": { "feature_name": { "type": "string", "maxLength": 5000, "minLength": 1, "description": "Name of the application feature to assess. Must match the 'name' field of an entry in the features artifact produced by the workflow run referenced in resume" }, "perspective": { "type": "string", "enum": [ "Injection", "XSS", "CSRF", "Authorization", "FileSystem", "BusinessLogic", "OpenRedirect", "SSRF", "Authentication", "Clickjacking", "CORS" ], "description": "Security testing perspective to apply to the feature" }, "priority": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "Assessment priority for this pair. Higher-priority pairs are assessed first. When omitted; the system determines priority automatically" } }, "additionalProperties": false, "type": "object", "required": [ "feature_name", "perspective" ] }, "type": "array", "maxItems": 10000, "description": "Specific feature–perspective pairs to assess. When omitted; all discovered features are assessed against all applicable perspectives. When specified; only the listed pairs are assessed. Requires 'resume' to be set. When using 'resume.continue_assessment'; pairs already in scan_progress are carried over automatically and only pairs absent in scan_progress will be freshly assessed" } }, "additionalProperties": false, "type": "object", "required": [ "language", "target_urls" ], "description": "Workflow-specific input parameters" }, "notification": { "properties": { "webhook_endpoint_ids": { "items": { "type": "string" }, "type": "array", "maxItems": 100, "minItems": 1, "description": "IDs of the registered webhook endpoints to notify when the workflow run completes" } }, "additionalProperties": false, "type": "object", "required": [ "webhook_endpoint_ids" ], "description": "Optional notification configuration for the workflow run" } }, "additionalProperties": false, "type": "object", "required": [ "input" ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "workflow_run_id": { "type": "string", "description": "The ID of the newly created workflow run" } }, "type": "object", "required": [ "workflow_run_id" ] } } }, "description": "Successful response" } }, "summary": "Dispatch a blackbox-assessment workflow run" } }, "/o/{orgID}/workflows/blackbox-assessment/get-artifact-download-url": { "post": { "description": "To list the available artifacts for a workflow run, use the `/blackbox-assessment/describe` endpoint.", "parameters": [ { "$ref": "#/components/parameters/orgID" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "workflow_run_id": { "type": "string", "maxLength": 256, "minLength": 1, "description": "The ID of the workflow run that produced the artifact" }, "artifact_name": { "type": "string", "maxLength": 256, "minLength": 1, "description": "The name of the artifact to download" } }, "additionalProperties": false, "type": "object", "required": [ "workflow_run_id", "artifact_name" ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "description": "URL to download the artifact via HTTP GET" }, "expires_in_seconds": { "type": "integer", "description": "Number of seconds until the download URL expires" } }, "type": "object", "required": [ "url", "expires_in_seconds" ] } } }, "description": "Successful response" } }, "summary": "Get artifact download URL for a blackbox-assessment workflow run" } }, "/o/{orgID}/workflows/blackbox-crawl/cancel": { "post": { "parameters": [ { "$ref": "#/components/parameters/orgID" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "workflow_run_id": { "type": "string", "maxLength": 256, "minLength": 1, "description": "The ID of the workflow run to cancel" } }, "additionalProperties": false, "type": "object", "required": [ "workflow_run_id" ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": {}, "type": "object" } } }, "description": "Successful response" } }, "summary": "Cancel a blackbox-crawl workflow run" } }, "/o/{orgID}/workflows/blackbox-crawl/describe": { "post": { "description": "To download the artifacts listed in the response, use the `/blackbox-crawl/get-artifact-download-url` endpoint.", "parameters": [ { "$ref": "#/components/parameters/orgID" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "workflow_run_id": { "type": "string", "maxLength": 256, "minLength": 1, "description": "The ID of the workflow run to describe" } }, "additionalProperties": false, "type": "object", "required": [ "workflow_run_id" ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "enum": [ "RUNNING", "EXITED" ], "title": "Status", "description": "Current status of the workflow run" }, "output": { "properties": { "kind": { "type": "string", "enum": [ "SUCCESS", "ABORTED" ], "description": "Whether the workflow run succeeded or was aborted" }, "successOutput": { "properties": { "features": { "properties": { "artifact_name": { "type": "string", "description": "The name of the artifact" } }, "type": "object", "required": [ "artifact_name" ], "description": "A JSON file containing the list of application features discovered during the crawl. The schema is available at `/v1/docs/workflow-artifacts/blackbox-crawl/features.json`" } }, "type": "object", "required": [ "features" ], "description": "The success output. Present only when kind is SUCCESS" }, "abortedReason": { "properties": { "code": { "type": "string", "description": "The abort reason code" }, "detail": { "description": "Type-specific detail for the abort reason" } }, "type": "object", "required": [ "code" ], "description": "The reason the workflow run was aborted. Present only when kind is ABORTED" } }, "type": "object", "required": [ "kind" ], "description": "Output of the workflow run. Present only when status is EXITED" }, "artifacts": { "items": { "properties": { "name": { "type": "string", "description": "Name of the artifact" } }, "type": "object", "required": [ "name" ] }, "type": "array", "description": "Downloadable artifacts produced by the workflow run. Present only when status is EXITED" } }, "type": "object", "required": [ "status" ] } } }, "description": "Successful response" } }, "summary": "Describe a blackbox-crawl workflow run" } }, "/o/{orgID}/workflows/blackbox-crawl/dispatch": { "post": { "description": "Dispatches a blackbox crawl and returns immediately. A crawl discovers application features without performing security testing. Poll the `/blackbox-crawl/describe` endpoint to check status. After the crawl completes; use the features artifact to select specific feature–perspective pairs for a subsequent blackbox-assessment run.", "parameters": [ { "$ref": "#/components/parameters/orgID" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "input": { "properties": { "language": { "type": "string", "enum": [ "english", "japanese" ] }, "target_urls": { "items": { "type": "string", "maxLength": 5000, "format": "uri", "description": "A fully qualified URL (e.g. https://app.example)" }, "type": "array", "maxItems": 100, "minItems": 1, "description": "Web application URLs to crawl. Each URL must belong to an application whose ownership has been verified; otherwise the workflow run will be rejected. See https://shisho.dev/docs/t/concepts/assessment-authentication/ for setup instructions" }, "oos_urls": { "items": { "type": "string", "maxLength": 5000, "format": "uri", "description": "A fully qualified URL (e.g. https://app.example)" }, "type": "array", "maxItems": 100, "description": "Out-of-scope URLs to exclude from crawling" }, "authentication": { "properties": { "credentials": { "items": { "properties": { "id": { "type": "string", "maxLength": 256, "minLength": 1, "description": "Login ID such as a username or email address" }, "password": { "type": "string", "maxLength": 5000, "description": "Login password" }, "role": { "type": "string", "maxLength": 256, "minLength": 1, "description": "Role label for this credential (e.g. \"admin\" or \"regular user\")" } }, "additionalProperties": false, "type": "object", "required": [ "id", "password", "role" ] }, "type": "array", "maxItems": 100, "minItems": 1, "description": "Login credentials for authenticated testing" }, "additional_instructions": { "type": "string", "maxLength": 5000, "minLength": 1, "description": "Additional instructions for the authentication process (e.g. login page URL; MFA setup steps)" } }, "additionalProperties": false, "type": "object", "description": "Credentials and instructions for logging into the target web application" }, "preference": { "properties": { "preferences": { "items": { "properties": { "kind": { "type": "string", "enum": [ "DO", "DONT" ], "description": "DO for a positive instruction; DONT for a negative instruction" }, "preference": { "type": "string", "maxLength": 5000, "minLength": 1, "description": "The instruction text (e.g. \"Please check the authentication feature\" for DO; \"No need to check the logging feature\" for DONT)" } }, "additionalProperties": false, "type": "object", "required": [ "kind", "preference" ] }, "type": "array", "maxItems": 100, "minItems": 1, "description": "Custom instructions to guide the assessment behavior. Note: Takumi does not always follow these instructions" } }, "additionalProperties": false, "type": "object", "description": "Custom instructions to guide the crawl. Note: Takumi does not always follow these instructions" }, "credit_limit": { "type": "integer", "maximum": 100000, "minimum": 5, "description": "Maximum number of credits to consume during crawling. When the limit is reached; the crawl completes successfully with all features discovered so far; results can be extended by resuming with additional credits" }, "additional_instructions": { "type": "string", "maxLength": 5000, "minLength": 1, "description": "Additional instructions for crawling (e.g. 'Focus on crawling the APIs (/api/v1/users/...) used by the page accessible at /page/abc')" }, "resume": { "properties": { "workflow_id": { "type": "string", "maxLength": 256, "minLength": 1, "description": "The ID of the workflow that produced the referenced run. Must be 'blackbox-crawl'" }, "workflow_run_id": { "type": "string", "maxLength": 256, "minLength": 1, "description": "ID of the blackbox-crawl run to resume from. The run must have exited with status SUCCESS" } }, "additionalProperties": false, "type": "object", "required": [ "workflow_id", "workflow_run_id" ], "description": "Resume crawling from a previous blackbox-crawl run; previously discovered features are preserved and the agent continues from where it left off. Note: resuming does not guarantee new endpoints will be discovered; credits are consumed even if no new endpoints are found" } }, "additionalProperties": false, "type": "object", "required": [ "language", "target_urls" ], "description": "Workflow-specific input parameters" }, "notification": { "properties": { "webhook_endpoint_ids": { "items": { "type": "string" }, "type": "array", "maxItems": 100, "minItems": 1, "description": "IDs of the registered webhook endpoints to notify when the workflow run completes" } }, "additionalProperties": false, "type": "object", "required": [ "webhook_endpoint_ids" ], "description": "Optional notification configuration for the workflow run" } }, "additionalProperties": false, "type": "object", "required": [ "input" ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "workflow_run_id": { "type": "string", "description": "The ID of the newly created workflow run" } }, "type": "object", "required": [ "workflow_run_id" ] } } }, "description": "Successful response" } }, "summary": "Dispatch a blackbox-crawl workflow run" } }, "/o/{orgID}/workflows/blackbox-crawl/get-artifact-download-url": { "post": { "description": "To list the available artifacts for a workflow run, use the `/blackbox-crawl/describe` endpoint.", "parameters": [ { "$ref": "#/components/parameters/orgID" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "workflow_run_id": { "type": "string", "maxLength": 256, "minLength": 1, "description": "The ID of the workflow run that produced the artifact" }, "artifact_name": { "type": "string", "maxLength": 256, "minLength": 1, "description": "The name of the artifact to download" } }, "additionalProperties": false, "type": "object", "required": [ "workflow_run_id", "artifact_name" ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "description": "URL to download the artifact via HTTP GET" }, "expires_in_seconds": { "type": "integer", "description": "Number of seconds until the download URL expires" } }, "type": "object", "required": [ "url", "expires_in_seconds" ] } } }, "description": "Successful response" } }, "summary": "Get artifact download URL for a blackbox-crawl workflow run" } }, "/o/{orgID}/workflows/whitebox-assessment/cancel": { "post": { "parameters": [ { "$ref": "#/components/parameters/orgID" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "workflow_run_id": { "type": "string", "maxLength": 256, "minLength": 1, "description": "The ID of the workflow run to cancel" } }, "additionalProperties": false, "type": "object", "required": [ "workflow_run_id" ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": {}, "type": "object" } } }, "description": "Successful response" } }, "summary": "Cancel a whitebox-assessment workflow run" } }, "/o/{orgID}/workflows/whitebox-assessment/describe": { "post": { "description": "To download the artifacts listed in the response, use the `/whitebox-assessment/get-artifact-download-url` endpoint.", "parameters": [ { "$ref": "#/components/parameters/orgID" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "workflow_run_id": { "type": "string", "maxLength": 256, "minLength": 1, "description": "The ID of the workflow run to describe" } }, "additionalProperties": false, "type": "object", "required": [ "workflow_run_id" ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "enum": [ "RUNNING", "EXITED" ], "title": "Status", "description": "Current status of the workflow run" }, "output": { "properties": { "kind": { "type": "string", "enum": [ "SUCCESS", "ABORTED" ], "description": "Whether the workflow run succeeded or was aborted" }, "successOutput": { "properties": { "report": { "properties": { "artifact_name": { "type": "string", "description": "The name of the artifact" } }, "type": "object", "required": [ "artifact_name" ], "description": "The assessment report in Markdown format" }, "findings": { "properties": { "artifact_name": { "type": "string", "description": "The name of the artifact" } }, "type": "object", "required": [ "artifact_name" ], "description": "A JSON file containing the list of vulnerability findings. The schema is available at `/v1/docs/workflow-artifacts/whitebox-assessment/findings.json`" } }, "type": "object", "required": [ "report", "findings" ], "description": "The success output. Present only when kind is SUCCESS" }, "abortedReason": { "properties": { "code": { "type": "string", "description": "The abort reason code" }, "detail": { "description": "Type-specific detail for the abort reason" } }, "type": "object", "required": [ "code" ], "description": "The reason the workflow run was aborted. Present only when kind is ABORTED" } }, "type": "object", "required": [ "kind" ], "description": "Output of the workflow run. Present only when status is EXITED" }, "artifacts": { "items": { "properties": { "name": { "type": "string", "description": "Name of the artifact" } }, "type": "object", "required": [ "name" ] }, "type": "array", "description": "Downloadable artifacts produced by the workflow run. Present only when status is EXITED" } }, "type": "object", "required": [ "status" ] } } }, "description": "Successful response" } }, "summary": "Describe a whitebox-assessment workflow run" } }, "/o/{orgID}/workflows/whitebox-assessment/dispatch": { "post": { "description": "Dispatches a whitebox assessment and returns immediately. Poll the `/whitebox-assessment/describe` endpoint to check status. Depending on the complexity of the target application, execution may take anywhere from several hours to several days.", "parameters": [ { "$ref": "#/components/parameters/orgID" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "input": { "properties": { "language": { "type": "string", "enum": [ "english", "japanese" ] }, "targets": { "items": { "properties": { "file_upload": { "properties": { "file_id": { "type": "string", "maxLength": 256, "minLength": 1, "description": "File ID returned by the input files upload API" }, "archive_type": { "type": "string", "enum": [ "zip", "tar_gz" ], "description": "Archive format of the uploaded file" } }, "additionalProperties": false, "type": "object", "required": [ "file_id", "archive_type" ], "description": "Source code archive uploaded via the input files API" } }, "additionalProperties": false, "type": "object", "required": [ "file_upload" ] }, "type": "array", "maxItems": 100, "minItems": 1, "description": "Source code archives to analyze" }, "preference": { "properties": { "preferences": { "items": { "properties": { "kind": { "type": "string", "enum": [ "DO", "DONT" ], "description": "DO for a positive instruction; DONT for a negative instruction" }, "preference": { "type": "string", "maxLength": 5000, "minLength": 1, "description": "The instruction text (e.g. \"Please check the authentication feature\" for DO; \"No need to check the logging feature\" for DONT)" } }, "additionalProperties": false, "type": "object", "required": [ "kind", "preference" ] }, "type": "array", "maxItems": 100, "minItems": 1, "description": "Custom instructions to guide the assessment behavior. Note: Takumi does not always follow these instructions" } }, "additionalProperties": false, "type": "object", "description": "Custom instructions to guide the assessment. Note: Takumi does not always follow these instructions" } }, "additionalProperties": false, "type": "object", "required": [ "language", "targets" ], "description": "Workflow-specific input parameters" }, "notification": { "properties": { "webhook_endpoint_ids": { "items": { "type": "string" }, "type": "array", "maxItems": 100, "minItems": 1, "description": "IDs of the registered webhook endpoints to notify when the workflow run completes" } }, "additionalProperties": false, "type": "object", "required": [ "webhook_endpoint_ids" ], "description": "Optional notification configuration for the workflow run" } }, "additionalProperties": false, "type": "object", "required": [ "input" ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "workflow_run_id": { "type": "string", "description": "The ID of the newly created workflow run" } }, "type": "object", "required": [ "workflow_run_id" ] } } }, "description": "Successful response" } }, "summary": "Dispatch a whitebox-assessment workflow run" } }, "/o/{orgID}/workflows/whitebox-assessment/get-artifact-download-url": { "post": { "description": "To list the available artifacts for a workflow run, use the `/whitebox-assessment/describe` endpoint.", "parameters": [ { "$ref": "#/components/parameters/orgID" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "workflow_run_id": { "type": "string", "maxLength": 256, "minLength": 1, "description": "The ID of the workflow run that produced the artifact" }, "artifact_name": { "type": "string", "maxLength": 256, "minLength": 1, "description": "The name of the artifact to download" } }, "additionalProperties": false, "type": "object", "required": [ "workflow_run_id", "artifact_name" ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "description": "URL to download the artifact via HTTP GET" }, "expires_in_seconds": { "type": "integer", "description": "Number of seconds until the download URL expires" } }, "type": "object", "required": [ "url", "expires_in_seconds" ] } } }, "description": "Successful response" } }, "summary": "Get artifact download URL for a whitebox-assessment workflow run" } } } }