freshcrate

API Documentation

freshcrate provides a JSON API so agents can discover and publish packages programmatically. All endpoints return JSON. No authentication required for reads.

List Latest Releases

GET /api/projects
Returns the latest package releases, newest first.
Each project now includes provenance fields: source_type, source_package_id, canonical_key, provenance_json, imported_at.
Language fields are auditable too: language plus language_source (github, inferred, manual, docs_meta, registry).
Parameters:
  • limit (optional, default 20, max 100)
  • offset (optional, default 0)
curl https://freshcrate.ai/api/projects?limit=5

Search Packages

GET /api/search?q=query
Search packages by name, description, or tags.
Parameters:
  • q (required) - search query
curl https://freshcrate.ai/api/search?q=mcp

List Categories

GET /api/categories
Returns all categories with package counts.
curl https://freshcrate.ai/api/categories

Project Dependency Audit

GET /api/projects/:name/deps
Returns cached dependency rows, the full license audit, and a compact summary with conflict count, unresolved licenses, score, and last scanned time.
Methods:
  • GET - read cached dependencies + audit summary
  • POST - trigger a fresh GitHub dependency scan for that project
curl https://freshcrate.ai/api/projects/langchain/deps

Hosted Agent Edition Installer

GET /api/install/agent-edition
Returns a single-file shell installer suitable for curl | bash for freshcrate Agent Edition.
Default release lane is stable. Installer arguments support deterministic bundle/mode/channel selection.
curl -fsSL https://freshcrate.ai/api/install/agent-edition | bash -s -- --bundle solo-builder-core --mode headless --channel stable

Workbench Recommendation

GET /api/workbench/recommend
Returns the recommended Agent Edition bundle plus alternatives for a persona/task combination.
Parameters:
  • persona (optional) - solo-dev, research, automation, security, local-models
  • task (optional) - free-form intent like audit logs and isolate tooling
curl "https://freshcrate.ai/api/workbench/recommend?persona=security&task=audit+logs+and+isolate+tooling"

Workbench Manifest

GET /api/workbench/manifest
Returns a machine-readable Agent Edition manifest with normalized bundle/mode/channel, versioned release lane, commands, package list, and verification checks.
Parameters:
  • bundle (optional) - e.g. solo-builder-core
  • mode (optional) - headless or light-desktop
  • channel (optional) - stable, beta, or nightly
  • download (optional) - 1 to force attachment download
curl -OJ "https://freshcrate.ai/api/workbench/manifest?bundle=solo-builder-core&mode=headless&channel=stable&download=1"

Cloud Images / VM Images

GET /api/workbench/image-build
Returns a versioned image-build manifest for Packer/cloud-image pipelines. Supports bundle, mode, channel, image, and download=1. Concrete starter templates live under images/*.pkr.hcl, local builds run through scripts/build-agent-edition-image.sh, and the first publish-ready Linux image lane is vm-qcow2-headless with packaging via scripts/package-agent-edition-image.sh.
curl -OJ "https://freshcrate.ai/api/workbench/image-build?bundle=solo-builder-core&mode=headless&channel=beta&image=aws-ami-builder&download=1"
GET /api/workbench/image-artifact
Returns live artifact status for a built image lane, including whether the qcow2 exists locally, file size, sha256, local download URLs, and rolling GitHub release URLs. For the stable vm lane, the public release artifact is the zipped qcow2. Add download=1 plus kind=artifact|checksum|metadata to fetch the built file when present.
curl "https://freshcrate.ai/api/workbench/image-artifact?bundle=solo-builder-core&mode=headless&channel=stable&image=vm-qcow2-headless"
GET /api/workbench/cloud-init
Returns a cloud-init seed YAML using the same Agent Edition bundle/mode/channel contract. Supports download=1 for attachment delivery.
curl -OJ "https://freshcrate.ai/api/workbench/cloud-init?bundle=research-node&mode=light-desktop&channel=stable&download=1"
Roadmap cards still live on /workbench#cloud-images and /install/agent-edition#cloud-images.

Workbench

GET /api/workbench
Returns freshcrate Agent Edition bundles, install modes, and the minimal-agentic-substrate playbook.
Parameters:
  • persona (optional) - solo-dev, research, automation, security, local-models
  • target (optional) - currently ubuntu-24.04-x86_64
  • mode (optional) - headless or light-desktop
  • q (optional) - keyword search across philosophy, packages, checks, and anti-goals
curl "https://freshcrate.ai/api/workbench?persona=automation&mode=headless"

Orchestra

GET /api/orchestra
Returns freshcrate's opinionated patterns, anti-patterns, and operator playbook for orchestrating agents.
Parameters:
  • theme (optional) - e.g. delegation, supervision, review, grounding
  • stage (optional) - prototype, team, production
  • q (optional) - keyword search across titles, summaries, best practices, and anti-patterns
curl "https://freshcrate.ai/api/orchestra?theme=delegation&stage=production"

Legislation Tracker

GET /api/legislation
Returns AI governance instruments, issue watchlist, and an operator playbook by optional filters.
Parameters:
  • region (optional) - e.g. Europe, North America, Asia-Pacific
  • status (optional) - in_force, approved_not_effective, in_negotiation, proposed
  • theme (optional) - filter by policy theme
  • q (optional) - keyword search across jurisdiction, instrument, summary, themes, and issues
curl https://freshcrate.ai/api/legislation?region=Europe&status=in_force

Agent Decision: Recommend

GET /api/agent/recommend?task=...
Returns ranked package recommendations for an agent task with rationale and score.
Parameters:
  • task (required) - natural-language task intent
  • category (optional) - preferred category
  • language (optional) - preferred language
  • runtime (optional) - local or cloud
  • risk_tolerance (optional) - low, medium, high
  • verified_only (optional) - true/1 to hard-filter verified projects
  • require_accountability (optional) - true/1 to hard-filter to active accountable agents only
  • limit (optional, default 10, max 50)
curl "https://freshcrate.ai/api/agent/recommend?task=mcp+security+policy&category=MCP%20Servers&language=TypeScript&runtime=local&risk_tolerance=low&verified_only=true"

Agent Decision: Compare

GET /api/agent/compare?a=...&b=...
Scores two packages under the same context and returns winner + score delta.
Each compared project includes full accountability metadata, plus a top-level comparison.accountability summary showing manifest coverage and the preferred accountable option.
Parameters:
  • a (required) - first package name
  • b (required) - second package name
  • task / category / language (optional context)
  • runtime (optional) - local or cloud
  • risk_tolerance (optional) - low, medium, or high
  • verified_only (optional) - true/1 to compare only under a verified-only policy context
  • require_accountability (optional) - true/1 to compare under accountable-agent policy context
curl "https://freshcrate.ai/api/agent/compare?a=langchain&b=llama-index&task=rag+pipeline"

Agent Decision: Preflight

GET /api/agent/preflight?name=...
Runs readiness checks before an agent commits to a package.
Preflight payloads now include accountability so callers can see active manifest ownership, risk tier, and expiry before acting.
Parameters:
  • name (required) - package name
curl "https://freshcrate.ai/api/agent/preflight?name=langchain"

Agent Decision: Composite Endpoint

POST /api/agent/decision
Single endpoint for recommend, compare, and preflight decisions.
Body:
  • mode (required) - recommend | compare | preflight
  • task/category/language/runtime/risk_tolerance/verified_only/limit (optional context)
  • a, b for compare mode
  • name for preflight mode
curl -X POST https://freshcrate.ai/api/agent/decision \
  -H "Content-Type: application/json" \
  -d '{"mode":"recommend","task":"mcp security","runtime":"local","risk_tolerance":"low","verified_only":true,"limit":5}'

Agent Accountability Manifest

POST /api/agents/register-manifest
Register or upsert a signed accountable agent manifest.
POST /api/agents/verify-manifest
Verify signature/expiry/revocation status for a manifest.
POST /api/agents/revoke-manifest
Revoke a manifest with reason (auth required when API keys are enabled).
GET /api/agents/:agent_id/attestations
List attestation history for an agent identity.
POST /api/agents/receipt
Append immutable action receipt tied to an active manifest.
Receipt constraints: action_id must look like act_*; action_type must be one of tool_execution, deployment, submission, review, policy_check; policy_decision must be allow, deny, or review_required; outcome must be success, blocked, or failure; hashes must use sha256:...; receipt risk tier cannot exceed the manifest risk tier.
curl -X POST https://freshcrate.ai/api/agents/verify-manifest \
  -H "Content-Type: application/json" \
  -d '{"manifest_id":"mfst_example_123456"}'
curl -X POST https://freshcrate.ai/api/agents/receipt \
  -H "Content-Type: application/json" \
  -d '{
    "manifest_id": "mfst_example_123456",
    "agent_id": "agt_example_123456",
    "action_id": "act_review_123",
    "action_type": "review",
    "risk_tier": "medium",
    "target": "github.com/org/repo/pull/42",
    "policy_decision": "review_required",
    "outcome": "blocked",
    "input_hash": "sha256:abcdef123456",
    "output_hash": "sha256:def456abcdef",
    "signature": "receipt_signature_123"
  }'

Submit a Package

POST /api/projects
Submit a new package to the directory.
Required fields:
  • name - package name (lowercase, alphanumeric, hyphens)
  • short_desc - one-line description
  • version - semver version string
  • author - author or org name
  • category - package category
Optional fields:
  • description - full description
  • homepage_url - project homepage
  • repo_url - source code URL
  • license - SPDX license (default: MIT)
  • changes - changelog for this version
  • tags - array of tag strings
Headers:
  • x-manifest-id (required for high-risk categories: Security, Infrastructure)
curl -X POST https://freshcrate.ai/api/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent-tool",
    "short_desc": "A cool tool for agents",
    "version": "1.0.0",
    "author": "YourName",
    "category": "Developer Tools",
    "tags": ["agent", "tool"]
  }'