---
title: "Issue or reuse an immutable recorded Run Card."
method: POST
path: "/api/run-cards"
tags: ["Run Cards"]
---

# Issue or reuse an immutable recorded Run Card.

`POST /api/run-cards`

## Request

- Base URL: `https://huggingbay.xyz`
- URL: `https://huggingbay.xyz/api/run-cards`
- Auth: HTTP bearer

Requires a publisher or admin bearer token exactly matching the principal and owner signed into the persisted automation policy evidence. administrator access and wildcard owner scope do not bypass that binding. The request identifies one hbap_* automation preflight; task, paths, runtime intent, policy, and recorded representation bindings cannot be supplied or overridden.

**Inputs.** No path or query fields are required. The request body schema lists accepted fields and required values.

**Outputs.** See each status below for its media type, schema and headers. A missing record or unavailable capability is not a successful empty result.

**Errors.** API JSON failures use the documented response schema. Read code, message and next; retry only when the response allows it. Auth, invalid input and missing records need a caller change.

**Rate limits.** Write and protocol operations can have separate route-specific limits. Read Retry-After and retry_after_s when present; do not infer a write allowance from the public read budget.

**Example setup.** Set HUGGING_BAY_TOKEN to a credential with the role or scope stated by this operation. Reader tokens do not grant publisher or operator rights. This example is not executed by documentation checks. Review the operation and obtain any required user consent before sending it. Replace sample identifiers, digests, tokens and results with your own recorded evidence. Report only runs or outcomes you observed. Read any license obligations before accepting them.

## Request body

- RunCardIssueRequest
  - `preflightId` string, required

## Response `200`

Existing immutable Run Card. When an accepted-run proof mapping exists, the response links it without changing the signed card body.

- RunCard
  - `schema` 'hugging-bay.run-card.v1', required
  - `contractVersion` '1.1.0', required
  - `id` string, required
  - `decisionId` string, required
  - `agentHandoffId` string, required
  - `publisherReferralId` string
  - `signingKeyId` string, required
  - `task` string, required
  - `constraints` object, required
    - `contextTokens` integer
    - `maxDownloadBytes` integer
    - `maxDiskBytes` integer
    - `commercialSafe` boolean
    - `privacy` string
    - `bandwidthClass` string
    - `qualityFloor` string
    - `language` string
  - `rig` object, required
    - `id` string, required
    - `profileDigest` string, required
  - `representation` object, required
    - `artifactId` string, required
    - `representationId` string, required
    - `source` object, required
      - `provider` string, required
      - `identity` string, required
      - `revision` string, required
    - `selectedFilesDigest` string, required
    - `representationDigest` string, required
    - `evidenceSnapshotDigest` string, required
    - `files` object[], required
      - `path` string, required
      - `role` string, required
      - `sizeBytes` integer, required
      - `sha256` string, required
  - `runtime` object, required
    - `adapterId` 'llama.cpp' | 'sentence-transformers' | 'transformers', required
    - `engineVersion` string, required
    - `adapterVersion` string, required
    - `adapterAbiVersion` string, required
    - `executable` 'hbay-runtime', required
    - `contractDigest` string, required
    - `commandEvidenceDigest` string, required
    - `argv` string[], required
  - `fit` object, required
    - `verdict` 'fits', required
    - `evidenceLevel` 'measured' | 'conservative-estimate', required
    - `requiredBytes` integer, required
    - `headroomBytes` integer, required
    - `evidenceDigest` string, required
  - `smoke` object, required
    - `suiteId` string, required
    - `expectedBoundary` string, required
    - `passed` unknown, required
    - `passedAt` string, date-time, required
    - `evidenceDigest` string, required
  - `recovery` object, required
    - `code` string, required
    - `path` string, required
  - `policy` object, required
    - `decision` 'allow', required
    - `policyDigest` string, required
    - `reasonCodes` string[], required
    - `expiresAt` string, date-time, required
  - `evidenceCutoff` string, date-time, required
  - `executableState` 'complete-runnable' | 'complete-verified', required
  - `authority` object, required
    - `automationPreflightId` string, required
    - `decisionDigest` string, required
    - `policyEvidenceId` string, required
    - `policyEvidenceDigest` string, required
  - `authorization` object, required
    - `principalId` string, required
    - `owner` string, required
  - `use` object, required
    - `argv` unknown[], required
      - unknown
  - `runCardDigest` string, required
  - `signature` object, required
    - `algorithm` 'Ed25519', required
    - `keyId` string, required
    - `canonicalDigest` string, required
    - `value` string, required

## Other responses

- `201`: New immutable Run Card. When an accepted-run proof mapping exists, the response links it without changing the signed card body.
- `400`: Malformed JSON request body
- `403`: Exact signed principal and owner authorization required
- `404`: Persisted preflight not found
- `409`: Preflight decision or recorded state is not executable
- `410`: Preflight evidence is expired, revoked, or no longer current
- `413`: Request body exceeds the 4 KiB endpoint limit
- `422`: Request or preflight identity is invalid
- `503`: Persistence, signing, or authoritative state unavailable

---

[API](https://skmtc.dev/huggingbay/apis/hugging-bay-public-api.md) · [All operations](https://skmtc.dev/huggingbay/apis/hugging-bay-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/huggingbay/apis/hugging-bay-public-api/revisions/63c474bf0fe4?raw)