---
title: "Record an informational security audit for the exact published version of a saved package: its published commit plus ..."
method: POST
path: "/v1/packages/{package_id}/security-audits"
tags: ["packages"]
---

# Record an informational security audit for the exact published version of a saved package: its published commit plus ...

`POST /v1/packages/{package_id}/security-audits`

## Request

- Base URL: `https://api.kody.codes`
- URL: `https://api.kody.codes/v1/packages/{package_id}/security-audits`
- Auth: HTTP bearer

Record an informational security audit for the exact published version of a saved package: its published commit plus capability-set fingerprint (both shown in the security audit prompt on the package capability approval page, and in the security_audit next step packageUpdate returns when a package moves toward internet-visible). Review that version first: declared vs used credentials, leaked credentials, unintended public exposure, risky network hosts, and package storage use. Then record verdict pass or concerns with a plain-language summary. The audit is tied to that commit and fingerprint; a new publish or changed capability set reads as not audited again. Recording an audit approves nothing by itself. One exception: when a request to make the package internet-visible is already pending (packageUpdate internet_visible: true), recording verdict pass re-evaluates self-publish, which makes the package internet-visible without the owner click (self_published: true) when the resolved capability set is empty and nothing in its dependency tree declares a credential or another capability. Otherwise hand the owner approval_url next. Requires package:read (to review the source) as well as package:write. Token-shaped strings in the summary are redacted.

Org permission: `package:write`.

## Path parameters

- `package_id` string, required: Saved package id that was audited.

## Request body

- object
  - `published_commit` string, required: Published commit SHA that was reviewed. Must match the package current published commit.
  - `fingerprint` string, required: Capability-set fingerprint that was reviewed. Must match the package current capability fingerprint.
  - `verdict` 'pass' | 'concerns', required: `pass` when nothing concerning was found; `concerns` when the owner should look closer before approving.
  - `summary` string, required: Plain-language summary for the package owner: what was checked, what was found, and anything they should look at before approving. No secret values.
  - `auditor` string: Optional name of the agent or person who performed the review, shown as "Audited by …". Defaults to the signed-in user.

## Response `200`

Success.

- object
  - `ok` true, required
  - `audit_id` string, required
  - `package_id` string, required
  - `published_commit` string, required
  - `fingerprint` string, required
  - `verdict` 'pass' | 'concerns', required
  - `recorded_at` string, required
  - `audit_url` string, required
  - `approval_url` string, required: The package approval page to hand the owner next.
  - `next_step` string, required
  - `self_published` true: Present when this pass made the package internet-visible through self-publish for a pending internet-visible request.
  - `self_publish_blocker` string: Present when an internet-visible request is pending and self-publish still does not apply; the owner approves at approval_url. Same values as packageUpdate self_publish_blocker.

## Other responses

- `400`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `401`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `403`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `404`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `409`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `413`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `429`: Too many requests (edge IP/token limit) or an entitlement / plan-cap limit. Wait at least `Retry-After` seconds before retrying.
- `500`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `503`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `default`: Error envelope `{ "error": { "code", "message", "details"? } }`.

---

[API](https://skmtc.dev/kody/apis/kody-api.md) · [All operations](https://skmtc.dev/kody/apis/kody-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kody/apis/kody-api/revisions/a020ecedb82b?raw)