> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 启动代码扫描 (Devin API)
> 通过 v3 组织 API 对代码仓库启动新的 Devin 代码扫描，也可指定扫描 Profile 或提交 SHA
## 权限
需要[服务用户](/zh/api-reference/v3/service-users/members-service-users)或[个人访问令牌](/zh/api-reference/personal-access-tokens)，并在组织级别拥有 `UseCodeScans` 权限。
## 行为
将组织中 `repo_name` 的新代码扫描加入队列。扫描调度程序会异步启动扫描；响应将返回扫描记录，其初始 `status` 为 `waiting` 或 `pending`。轮询[列出代码扫描](/zh/api-reference/v3/code-scans/organizations-code-scans-list)以跟踪进度，并在扫描状态变为 `completed` 后，通过[列出代码扫描发现项](/zh/api-reference/v3/code-scans/organizations-code-scans-findings) (按 `scan_id` 过滤) 查看结果。
该扫描归属于调用主体 (即发出请求的服务用户或 PAT) 。Enterprise 作用域内的等效操作为[启动代码扫描 (Enterprise)](/zh/api-reference/v3/code-scans/enterprise-code-scans-start)。
### 请求字段
* `repo_name` (必填) ：完整的代码仓库名称，例如 `owner/repo`。该代码仓库必须已通过组织的 Git 集成获得访问权限。
* `host`：代码仓库所在的 Git 主机 (如果无法自动推断) 。
* `profile_id`：要应用的[扫描 Profile](/zh/api-reference/v3/code-scans/organizations-code-scans-profiles)。对于 `ingest` 模式的 Profile，请使用[启动摄取扫描](/zh/api-reference/v3/code-scans/organizations-code-scans-start-ingestion)。
* `scan_type`：要运行的扫描类型。指定 `profile_id` 时，必须与该 Profile 的扫描类型一致。默认使用 Profile 的类型；未指定 Profile 的扫描则默认使用 `security`。非安全扫描类型必须指定 Profile。
* `commit_sha`：扫描前要检出的提交。默认使用代码仓库默认分支的最新提交。
### 错误
* 当 `scan_type` 与 Profile 不匹配，或未提供 Profile 却指定了非安全类 `scan_type` 时，返回 `400`。
* 当组织仅允许摄取模式扫描，且未提供 `ingest` 模式的 Profile 时，返回 `403`。
* 当代码仓库或 Profile 对组织不可见时，返回 `404`。
* 当组织的扫描待办列表已满时，返回 `409`。请稍后重试。
## OpenAPI
````yaml zh/v3-openapi.yaml POST /v3/organizations/{org_id}/code-scans
openapi: 3.1.0
info:
description: 采用 Service User 身份验证和 RBAC 的 Devin v3 API
title: Devin API v3
version: 3.0.0
servers: []
security:
- bearerAuth: []
paths:
/v3/organizations/{org_id}/code-scans:
post:
tags:
- code-scans
summary: 启动代码扫描
description: |-
对组织中的代码仓库发起新的代码扫描。
扫描会加入队列，并由扫描调度器异步启动。
该扫描归属于发起调用的主体（即发出请求的服务用户或 PAT）。当组织的扫描待办列表达到容量上限时，返回 ``409``。
operationId: handle_start_code_scan_v3_organizations__org_id__code_scans_post
parameters:
- description: 组织 ID（前缀：org-）
in: path
name: org_id
required: true
schema:
example: org-abc123def456
title: Org Id
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CodeScanCreateRequest'
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/CodeScanResponse'
description: 成功响应
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetail'
description: 未授权
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetail'
description: 禁止访问
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetail'
description: 未找到
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetail'
description: 冲突
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetail'
description: 内容无法处理
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetail'
description: 请求过于频繁
components:
schemas:
CodeScanCreateRequest:
description: 用于启动新代码扫描的请求正文。
properties:
commit_sha:
anyOf:
- type: string
- type: 'null'
description: 扫描前要检出的提交。
title: Commit Sha
host:
anyOf:
- type: string
- type: 'null'
description: 代码仓库的 Git 主机（如果已知）。
title: Host
profile_id:
anyOf:
- type: string
- type: 'null'
description: 要应用于此次扫描的扫描 Profile。
title: Profile Id
repo_name:
description: 要扫描的代码仓库全名。
title: Repo Name
type: string
scan_type:
anyOf:
- enum:
- security
- performance
- db-queries
- test-coverage
- dead-code
- code-quality
- telemetry
- accessibility
- general
- migration-docs
type: string
- type: 'null'
description: >-
要运行的扫描类型。指定 Profile 时必须与该 Profile 的扫描类型匹配；默认使用该 Profile 的类型，未指定
Profile 的扫描则默认为 'security'。非安全类型必须指定 Profile，否则会被拒绝。
title: Scan Type
required:
- repo_name
title: CodeScanCreateRequest
type: object
CodeScanResponse:
description: 一次代码扫描。
properties:
created_at:
description: 扫描的创建时间（Unix 秒）。
title: Created At
type: integer
host:
anyOf:
- type: string
- type: 'null'
description: 代码仓库的 Git 托管平台（如已知）。
title: Host
org_id:
description: 该扫描所属的组织。
title: Org Id
type: string
profile:
anyOf:
- $ref: '#/components/schemas/CodeScanProfileResponse'
- type: 'null'
description: 扫描所使用的 Profile（如有）。
repo_name:
description: 扫描的主代码仓库。多代码仓库扫描还会涵盖此处未列出的其他代码仓库。
title: Repo Name
type: string
scan_id:
description: 扫描的唯一标识符。
title: Scan Id
type: string
scan_type:
description: 扫描类型，在创建时确定。
enum:
- security
- performance
- db-queries
- test-coverage
- dead-code
- code-quality
- telemetry
- accessibility
- general
- migration-docs
title: Scan Type
type: string
status:
description: >-
扫描状态：waiting、pending、running、awaiting_user_input、completed、failed 或
cancelled。
enum:
- waiting
- pending
- running
- awaiting_user_input
- completed
- failed
- cancelled
title: Status
type: string
required:
- scan_id
- org_id
- repo_name
- host
- status
- profile
- scan_type
- created_at
title: CodeScanResponse
type: object
ProblemDetail:
description: >-
v3 API 的 RFC 9457 application/problem+json 错误响应体。
detail 沿用自旧版 {"detail": ...} 响应体，以保持向后兼容；其他成员字段为新增字段。errors
包含字段级验证失败信息（仅 422）。
properties:
detail:
anyOf:
- type: string
- type: 'null'
description: 针对此次具体情况的、便于人理解的说明。
title: Detail
errors:
anyOf:
- items:
additionalProperties: true
type: object
type: array
- type: 'null'
description: 字段级验证错误（仅适用于 422 响应）。
title: Errors
instance:
anyOf:
- type: string
- type: 'null'
description: 此次出现对应的 URI 引用（请求路径）。
title: Instance
status:
description: HTTP 状态码。
title: Status
type: integer
title:
description: 对问题类型的简短、便于理解的概述。
title: Title
type: string
type:
default: about:blank
description: 用于标识问题类型的 URI 引用。
title: Type
type: string
required:
- title
- status
title: ProblemDetail
type: object
CodeScanProfileResponse:
description: 扫描所使用 Profile 的摘要。
properties:
name:
description: Profile 的名称。
title: Name
type: string
profile_id:
description: Profile 的唯一标识符。
title: Profile Id
type: string
required:
- profile_id
- name
title: CodeScanProfileResponse
type: object
securitySchemes:
bearerAuth:
description: 服务用户凭据（前缀：cog_）
scheme: bearer
type: http
````