Reference

REST endpoints, MCP tools, CLI commands, error codes, and rate-limit headers for Sigildex v0.8.0.

Base URL: https://sigildex.ai
OpenAPI: /openapi.json
MCP descriptor: /.well-known/mcp.json
x402 descriptor: /.well-known/x402.json
Identity and hash contract: /docs/identity

Endpoint	Job	Returns	Cost
`POST /discover`	Find candidate skills	Ranked candidates with compact provenance, structured install, and a nested safety summary	50 discovery workflows per day per IP free; then x402
`POST /inspect`	Decide whether to install one skill	Full content, source provenance, manifest, install options, canonical safety, and a pin block	Free with a valid `query_id`; otherwise same paid workflow bucket
`GET /verify`	Re-check a skill you already hold	Verdict and provenance for a source URL or content hash	Free, cacheable, no account
`GET /health`	Check liveness and index freshness	Version, uptime, freshness, descriptor links	Free

Search is how you find a skill. Verification is how you keep trusting it. Pin what you install from /inspect.pin, then call /verify on load or in CI. If upstream content drifts or the safety verdict changes, the response changes.

POST /discover

Search by natural-language query. /discover returns a compact picker shape: results[].skill_id, name, description, score, source {registry, url}, structured install {manager, package, skill?, command, requires_confirmation}, publisher fields, audit_status, verification_level, selection_flags, quantitative signals, and nested safety {status, recommended_action, executes_code, safety_flags}.

Keys with null values are omitted from /discover. Missing optional fields mean not assessed; empty arrays mean assessed and clean. meta.index_status is one of ok | degraded | rebuilding.


curl -X POST https://sigildex.ai/discover \
  -H "Content-Type: application/json" \
  -d '{"query": "PDF text extraction with OCR support", "limit": 5}'

POST /inspect

Inspect exactly one skill by skill_id, source_url, or content_hash. query_id is optional and only controls free entitlement; it is not a selector.


curl -X POST https://sigildex.ai/inspect \
  -H "Content-Type: application/json" \
  -d '{"skill_id": "<skill_id>", "query_id": "<query_id>"}'

/inspect returns full SKILL.md content, rich source provenance, structured install, manifest, install_options, publisher fields, audit_status plus audit_details, verification_level, full canonical safety, quantitative signals, and pin.

The full safety object is {status, recommended_action, executes_code, safety_flags, score, analyzed_at, safety_version, audited_content_hash, freshness, scope}. freshness is one of never_audited | stale_unverifiable | stale_content_drift | stale_scanner_version | fresh.

pin is lockfile-ready: {skill_id, source_url, content_hash, commit_sha, verdict, audited_at}. Store it with the installed skill and re-check it through /verify.

GET /verify

Free verdict lookup for content you already hold. Pass content_hash, source_url, or both:


curl "https://sigildex.ai/verify?content_hash=sha256:<hex>"
curl "https://sigildex.ai/verify?source_url=https%3A%2F%2Fgithub.com%2Forg%2Frepo%2Fblob%2Fmain%2FSKILL.md&content_hash=sha256:<hex>"

skill_id is not accepted on /verify. If both selector fields are supplied, source_url is resolved first and the supplied hash is treated as a cross-check. A well-formed miss returns HTTP 200 with {"matched": false, "verification": "unknown"}.

Hits include matched: true, matched_by, skill {skill_id, source_url, name}, match {your_hash_matches_audited, current_content_hash}, and the full canonical safety object. Hits send ETag and Cache-Control: public, max-age=300. Misses use Cache-Control: public, max-age=60.

GET /health

No payment and no rate limit. Returns status, version, uptime_seconds, index_fresh, skills_indexed, and descriptor links.


{
  "status": "ok",
  "version": "0.8.0",
  "uptime_seconds": 86400,
  "index_fresh": true,
  "skills_indexed": 128000,
  "links": {
    "openapi": "https://sigildex.ai/openapi.json",
    "x402": "https://sigildex.ai/.well-known/x402.json",
    "mcp": "https://sigildex.ai/.well-known/mcp.json",
    "docs": "https://sigildex.ai/llms.txt",
    "support": "https://sigildex.ai/docs"
  }
}

MCP Tools

discover_skills mirrors POST /discover.
inspect_skill mirrors POST /inspect.
verify_skill mirrors GET /verify. It is free and has no payment challenge in the loop.

Text fallbacks include Safety: <status> - <action hint>. Structured content mirrors the REST response plus MCP-only version.

CLI


npx @sigildex/cli search "PDF text extraction" --limit 3 --json
npx @sigildex/cli inspect <skill_id> --query-id <query_id> --json
npx @sigildex/cli verify --content-hash sha256:<hex> --json
npx @sigildex/cli health --json

Use SIGILDEX_WALLET_KEY to enable x402 auto-pay beyond the free discovery tier. Do not auto-run install commands; show the selected skill and ask for confirmation first.

Errors

Errors use {error: {code, message, is_retriable, retry_after_seconds, details?}}. Request-shape and selector validation return INVALID_REQUEST. Unknown inspect selectors return NOT_FOUND. Invalid or mismatched query_id returns INVALID_QUERY_ID with details.kind of expired | mismatched_skill | unknown. Free-tier exhaustion returns PAYMENT_REQUIRED; true rate limiting returns RATE_LIMITED.