Release Proof API

Agent Skill

Install the readable, repository-owned skill for Codex, Claude Code, Cursor, and other skills-compatible coding agents:

npx skills add Johnny-Z13/proofslip --skill proofslip-release-proof

The skill can verify an existing proof URL or prepare a minimal edit to the GitHub Actions workflow that actually releases the project. It inspects first, shows the proposed change, asks before editing, and does not commit, push, or release without separate authorization.

Read the skill, verification helper, and workflow template on GitHub.

Manual GitHub Actions quickstart

No ProofSlip account or API key is needed. The workflow requests a GitHub OIDC token whose audience is https://proofslip.ai, then exchanges it for a public proof.

permissions:
  contents: read
  id-token: write

steps:
  - name: Create release proof
    shell: bash
    run: |
      TOKEN="$(curl -sSf \
        -H "Authorization: bearer ${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" \
        "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=https%3A%2F%2Fproofslip.ai" \
        | jq -r .value)"

      BODY="$(jq -n \
        --arg key "${GITHUB_REPOSITORY}:${GITHUB_RUN_ID}:${GITHUB_RUN_ATTEMPT}" \
        '{idempotency_key:$key}')"

      curl --fail-with-body -sS \
        -X POST https://proofslip.ai/v1/proofs/releases/github-actions \
        -H "Authorization: Bearer ${TOKEN}" \
        -H "Content-Type: application/json" \
        --data "${BODY}"

The response includes proof_url for humans and proof_id for the JSON API.

Trust model

POST/v1/proofs/releases/github-actions

Send Authorization: Bearer <GitHub OIDC token>. The token must be signed by GitHub, use the ProofSlip audience, be inside its validity window, and contain the required workflow claims.

Optional request body

{
  "schema_version": "release-proof/v1",
  "idempotency_key": "owner/repo:run_id:attempt",
  "deployment": {
    "url": "https://app.example.com",
    "health_path": "/health"
  },
  "submitted_context": {
    "environment": "production",
    "label": "web release"
  }
}

Deployment checks accept only public HTTPS hosts on the default port. Redirects are not followed, response bodies are not read, and observation failure does not invalidate the provider-backed proof.

Response

{
  "proof_id": "prf_...",
  "proof_url": "https://proofslip.ai/proof/prf_...",
  "schema_version": "release-proof/v1",
  "is_valid": true,
  "is_expired": false,
  "trust_level": "provider_verified",
  "verification_method": "github_actions_oidc",
  "issuer": {
    "type": "github_actions",
    "repository": "owner/repo",
    "ref": "refs/heads/main",
    "sha": "...",
    "run_id": "...",
    "run_attempt": 1,
    "run_url": "https://github.com/owner/repo/actions/runs/..."
  },
  "observations": [],
  "submitted_context": null,
  "issued_at": "...",
  "expires_at": "..."
}

Returns 201 when created and 200 for an identical token replay or idempotent retry. Conflicting reuse returns 409.

GET/v1/proofs/{proof_id}

Returns the machine-readable proof. The human view is GET /proof/{proof_id}.

curl https://proofslip.ai/v1/proofs/prf_...

Within the 90-day validity window the response is 200. After expiry the full record remains inspectable, with is_expired: true, and the endpoint returns 410.

Public access and retention

Release proofs have a 90-day validity window. V1 keeps expired records inspectable rather than deleting them automatically. See the privacy policy before enabling this in a private repository.

Legacy receipt API

The original general-purpose receipt API remains operational for agent handshakes, approvals, resumable workflows, and short-lived action records. It is separate from provider-backed release proofs.

MCP: npx -y @proofslip/mcp-server. LangChain: pip install langchain-proofslip. These published integrations currently expose the legacy receipt tools.

Errors

{"error":"error_code","message":"Description","request_id":"req_..."}

Machine discovery