# Sigildex > Skill discovery and verification API for coding agents. REST + MCP + CLI. 50 discovery workflows per day per IP free; paid discovery uses x402 on Base. Verification is free. ## Core Flow 1. Call `GET /health` for liveness and version. 2. Call `POST /discover` to find candidates. 3. Reject `safety.recommended_action: "block"`. 4. Call `POST /inspect` for full content and `pin`. 5. Install only after user confirmation. 6. Call `GET /verify` or MCP `verify_skill` on future loads or in CI. ## Endpoints | 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 | ## Files - [OpenAPI](https://sigildex.ai/openapi.json) - [MCP descriptor](https://sigildex.ai/.well-known/mcp.json) - [x402 payment descriptor](https://sigildex.ai/.well-known/x402.json) - [All docs in one fetch](https://sigildex.ai/llms-full.txt) - [Quickstart](https://sigildex.ai/docs/quickstart) - [Reference](https://sigildex.ai/docs/api) - [Verification](https://sigildex.ai/docs/identity) - [Payments](https://sigildex.ai/docs/payments) --- ## Mirror: /docs/quickstart.md # Quickstart > Same index, ranking, safety, and verification through MCP, REST, and CLI. > **For AI agents:** fetch [`/llms.txt`](https://sigildex.ai/llms.txt) for the surface index, or [`/llms-full.txt`](https://sigildex.ai/llms-full.txt) for all docs in one fetch. Every docs page has a Markdown mirror at the same path with a `.md` suffix. Follow the Core Flow: reject any result whose `safety.recommended_action` is `block`, and re-check held skills with the free `GET /verify`. | 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. ## Which endpoint? | You have | Call | Cost | |---|---|---| | A task and no skill yet | `POST /discover` | Free tier (50/day per IP), then $0.002 per workflow | | A candidate `skill_id` to evaluate | `POST /inspect` | Free with the `query_id` from /discover (up to 5 inspects, 1h TTL) | | An installed skill to re-check | `GET /verify` | Always free | ## MCP ```json { "mcpServers": { "sigildex": { "url": "https://sigildex.ai/mcp" } } } ``` Your agent gets `discover_skills`, `inspect_skill`, and `verify_skill`. Use `verify_skill` when loading a pinned skill or checking CI because it is free and returns only verdict/provenance. ## REST ```bash curl -X POST https://sigildex.ai/discover \ -H "Content-Type: application/json" \ -d '{"query": "PDF text extraction", "limit": 3}' curl -X POST https://sigildex.ai/inspect \ -H "Content-Type: application/json" \ -d '{"skill_id": "", "query_id": ""}' curl "https://sigildex.ai/verify?content_hash=sha256:" ``` `/discover` returns `results[].skill_id`, nested `safety`, structured `install`, and `meta.index_status`. `/inspect` returns the full content and `pin`. `/verify` re-checks the pin by hash or source URL. ## CLI ```bash npx @sigildex/cli search "PDF text extraction" --limit 3 npx @sigildex/cli inspect --query-id --content-only npx @sigildex/cli verify --content-hash sha256: ``` Use `--json` for structured output. No wallet is needed for the free tier or `verify`. Set `SIGILDEX_WALLET_KEY` only when you want automatic paid discovery beyond the free tier. ## Worked example: discover, inspect, pin, verify The complete trust loop on one (illustrative) skill. The discover and inspect responses are abridged — the [Reference](https://sigildex.ai/docs/api) documents every field; the verify response is shown complete. **1. Discover.** ```bash curl -X POST https://sigildex.ai/discover \ -H "Content-Type: application/json" \ -d '{"query": "extract text from PDF files", "limit": 3}' ``` ```json { "query_id": "q_1f2e3d4c5b6a", "results": [ { "skill_id": "550e8400-e29b-41d4-a716-446655440000", "name": "pdf-reader", "score": 0.952, "source": { "registry": "github", "url": "https://github.com/example/skills/blob/main/pdf/SKILL.md" }, "safety": { "status": "safe", "recommended_action": "safe_to_install", "executes_code": false, "safety_flags": [] } } ], "meta": { "limit": 3, "total_results": 3, "index_status": "ok" } } ``` **2. Inspect the one you picked** — free with the `query_id`. ```bash curl -X POST https://sigildex.ai/inspect \ -H "Content-Type: application/json" \ -d '{"skill_id": "550e8400-e29b-41d4-a716-446655440000", "query_id": "q_1f2e3d4c5b6a"}' ``` ```json { "content": "---\nname: pdf-reader\n...", "safety": { "status": "safe", "recommended_action": "safe_to_install", "audited_content_hash": "sha256:7c0e84d2a91f4b3e5a6d8c0b1f2e3d4c5b6a79881726354403f9a2c41d7be019", "freshness": "fresh" }, "pin": { "skill_id": "550e8400-e29b-41d4-a716-446655440000", "source_url": "https://github.com/example/skills/blob/main/pdf/SKILL.md", "content_hash": "sha256:7c0e84d2a91f4b3e5a6d8c0b1f2e3d4c5b6a79881726354403f9a2c41d7be019", "commit_sha": "0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b", "verdict": "safe", "audited_at": "2026-06-01T00:00:00Z" } } ``` **3. Pin.** Review the content, confirm the install with your user, and store the `pin` object next to the installed skill — it is your lockfile entry. **4. Verify on every load** — free, no `query_id` needed. ```bash curl "https://sigildex.ai/verify?content_hash=sha256:7c0e84d2a91f4b3e5a6d8c0b1f2e3d4c5b6a79881726354403f9a2c41d7be019" ``` ```json { "matched": true, "matched_by": "content_hash", "skill": { "skill_id": "550e8400-e29b-41d4-a716-446655440000", "source_url": "https://github.com/example/skills/blob/main/pdf/SKILL.md", "name": "pdf-reader" }, "match": { "your_hash_matches_audited": true, "current_content_hash": "sha256:7c0e84d2a91f4b3e5a6d8c0b1f2e3d4c5b6a79881726354403f9a2c41d7be019" }, "safety": { "status": "safe", "recommended_action": "safe_to_install", "executes_code": false, "safety_flags": [], "score": 0.92, "analyzed_at": "2026-06-01T00:00:00Z", "safety_version": 2, "audited_content_hash": "sha256:7c0e84d2a91f4b3e5a6d8c0b1f2e3d4c5b6a79881726354403f9a2c41d7be019", "freshness": "fresh", "scope": "Verdict covers SKILL.md content and metadata signals only — not bundled scripts, dependencies, or install-time behavior." } } ``` If the upstream content drifts or the safety verdict changes, this response changes — your agent finds out before the skill loads, not after. ## Next - Full reference: [Reference](https://sigildex.ai/docs/api) - Payment integration: [Payments](https://sigildex.ai/docs/payments) - Verification, identity, and hashing: [Verification](https://sigildex.ai/docs/identity) --- ## Mirror: /docs/api.md # 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`](https://sigildex.ai/openapi.json) - MCP descriptor: [`/.well-known/mcp.json`](https://sigildex.ai/.well-known/mcp.json) - x402 descriptor: [`/.well-known/x402.json`](https://sigildex.ai/.well-known/x402.json) - Verification (identity and hash contract): [`/docs/identity`](https://sigildex.ai/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. > **For AI agents:** fetch [`/llms.txt`](https://sigildex.ai/llms.txt) for the surface index, or [`/llms-full.txt`](https://sigildex.ai/llms-full.txt) for all docs in one fetch. Every docs page has a Markdown mirror at the same path with a `.md` suffix. Follow the Core Flow: reject any result whose `safety.recommended_action` is `block`, and re-check held skills with the free `GET /verify`. ## 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`. ### Request example #### curl ```bash curl -X POST https://sigildex.ai/discover \ -H "Content-Type: application/json" \ -d '{"query":"PDF text extraction with OCR support","limit":5}' ``` #### Python ```python import requests response = requests.post( "https://sigildex.ai/discover", json={ "query": "PDF text extraction with OCR support", "limit": 5 }, ) response.raise_for_status() print(response.json()) ``` #### TypeScript ```typescript const response = await fetch("https://sigildex.ai/discover", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ "query": "PDF text extraction with OCR support", "limit": 5 }), }); if (!response.ok) throw new Error(await response.text()); console.log(await response.json()); ``` ### Request parameters - `query` (string, required) — Natural-language search query, 1-500 characters. - `limit` (integer, optional) — Maximum number of results to return; defaults to 10 and is capped at 30. - `rationale` (string, optional) — Why you're searching. Good: 'building a file-upload utility'. Avoid: 'the user wants X'. - `filters` (object, optional) — Optional discovery filters applied after the public source alias is resolved. - `filters.source` (string, enum "main" | "github", optional) — 'main' is the curated default corpus. 'github' explicitly asks for GitHub-hosted SKILL.md rows. - `filters.min_stars` (integer, optional) — Minimum GitHub star count for returned rows. - `filters.updated_after` (string, optional) — Only return rows updated after this ISO date-time. ### Response example ```json { "query_id": "q_7f3a2b1c9e4d", "results": [ { "skill_id": "550e8400-e29b-41d4-a716-446655440000", "name": "pdf-ocr", "description": "Extract text from scanned PDFs.", "score": 0.92, "source": { "registry": "github", "url": "https://github.com/org/repo/blob/main/SKILL.md" }, "install": { "manager": "skills", "package": "github:org/repo", "skill": "pdf-ocr", "command": "skills install github:org/repo --skill pdf-ocr", "requires_confirmation": true }, "publisher": "org", "publisher_verified": false, "safety": { "status": "safe", "recommended_action": "safe_to_install", "executes_code": false, "safety_flags": [] }, "audit_status": "pass", "verification_level": "tested", "selection_flags": [], "signals": { "indexed_at": "2026-06-12T00:00:00.000Z" } } ], "meta": { "total_results": 1, "limit": 5, "index_status": "ok" } } ``` ### Response fields - `query_id` (string, required) — Opaque discovery query identifier used to unlock free /inspect calls for matching skills. - `results` (array, required) — Ranked skill results. - `results[]` (object, required) — Compact v0.8 discover result. Null-valued optional keys are omitted. - `results[].skill_id` (string, required) — Skill UUID. Use with /inspect. - `results[].name` (string, required) — Skill display name. - `results[].description` (string, required) — Short skill description. - `results[].score` (number, required) — Composite ranking score. Use for ordering within a response. - `results[].source` (object, required) — Nested object. - `results[].source.registry` (string, enum "github" | "clawhub", required) — Registry where Sigildex indexed the skill. github: GitHub-hosted SKILL.md row. clawhub: legacy ClawHub row. - `results[].source.url` (string, required) — Human-browsable source URL. - `results[].install` (object, required) — Nested object. - `results[].install.manager` (string, enum "skills" | "manual", required) — Installer family. skills: install with the skills CLI. manual: manual install instructions. - `results[].install.package` (string, required) — Package or source identifier to install. - `results[].install.skill` (string, optional) — Skill name or package-local skill path when present. - `results[].install.command` (string, required) — Rendered command. Does not include --yes. - `results[].install.requires_confirmation` (boolean, required) — Whether autonomous agents should obtain user confirmation before running the command. - `results[].publisher` (string, required) — Publisher display name, or 'unknown' when absent. - `results[].publisher_verified` (boolean, required) — Whether the publisher has a verified signal. - `results[].safety` (object, required) — Nested object. - `results[].safety.status` (string, enum "safe" | "caution" | "warning" | "dangerous" | "unaudited", required) — Safety verdict from Sigildex analysis. safe: no known safety concern. caution: install is allowed but deserves review. warning: stronger safety concern, review before use. dangerous: known-dangerous rows are blocked from default /discover. unaudited: no current safety analysis is available. - `results[].safety.recommended_action` (string, enum "safe_to_install" | "review_before_install" | "block", required) — Agent-facing install recommendation derived from safety status and executes_code. safe_to_install: safe status and no registry-reported code execution — still check manifest.summary.has_scripts on /inspect before install. review_before_install: human or policy review recommended before install. block: do not install. - `results[].safety.executes_code` (boolean, required) — Presence-only code-execution flag sourced from registry metadata; at v0.8 it is populated only for rows from the frozen ClawHub snapshot, so GitHub rows report false even when the bundle contains scripts. Do not treat false as no-bundled-scripts — check manifest.summary.has_scripts on /inspect for bundle evidence. Script contents are never analyzed. - `results[].safety.safety_flags` (array, required) — Safety findings. Empty means assessed and clean. - `results[].safety.safety_flags[]` (string, required) — Safety findings. Empty means assessed and clean. - `results[].audit_status` (string, enum "pass" | "warn" | "fail" | "unaudited", required) — Third-party audit aggregate. pass: no audit concern. warn: audit warning. fail: audit failure. unaudited: no third-party audit result. - `results[].verification_level` (string, enum "unverified" | "declared" | "tested" | "formal", required) — Evidence level for the skill metadata. unverified: no independent verification. declared: publisher-declared only. tested: tested by Sigildex or an upstream source. formal: formal verification evidence. - `results[].skill_type` (string, enum "capability" | "discipline" | "workflow" | "domain" | "document_tool" | "meta_catalog", optional) — Optional skill taxonomy. capability: concrete agent capability. discipline: practice area. workflow: multi-step workflow. domain: domain-specific knowledge. document_tool: document-processing tool. meta_catalog: catalog or index skill. null: not classified. - `results[].quality_flags` (array, optional) — Only present when assessed; [] means assessed and clean. - `results[].quality_flags[]` (string, optional) — Only present when assessed; [] means assessed and clean. - `results[].selection_flags` (array, required) — Selection-critical claim flags detected from the skill name and description. - `results[].selection_flags[]` (string, required) — Selection-critical claim flags detected from the skill name and description. - `results[].cluster_id` (string, optional) — Cluster identifier for related skills when present. - `results[].score_explanation` (object, optional) — Reserved bucketed score explanation. Declared in the schema for a future release; v0.8 /discover responses do not emit this field. - `results[].score_explanation.match` (object, required) — Nested object. - `results[].score_explanation.match.level` (string, enum "strong" | "good" | "weak", required) — Reserved (not emitted at v0.8). Match contribution bucket. strong: strongest query match. good: acceptable match. weak: low-confidence match. - `results[].score_explanation.trust` (object, required) — Nested object. - `results[].score_explanation.trust.level` (string, enum "high" | "medium" | "low", required) — Reserved (not emitted at v0.8). Trust contribution bucket. high: strong publisher, install, and freshness inputs. medium: mixed inputs. low: weak inputs. - `results[].score_explanation.recency` (object, required) — Nested object. - `results[].score_explanation.recency.level` (string, enum "current" | "recent" | "stale", required) — Reserved (not emitted at v0.8). Recency contribution bucket. current: current upstream activity. recent: somewhat recent activity. stale: stale upstream activity. - `results[].score_explanation.quality` (object, required) — Nested object. - `results[].score_explanation.quality.level` (string, enum "good" | "ok" | "poor", required) — Reserved (not emitted at v0.8). Quality contribution bucket. good: strong quality signals. ok: acceptable quality. poor: weak quality signals. - `results[].score_explanation.safety` (object, required) — Nested object. - `results[].score_explanation.safety.level` (string, enum "safe" | "caution" | "warning" | "dangerous" | "unaudited", required) — Reserved (not emitted at v0.8). Safety verdict from Sigildex analysis. safe: no known safety concern. caution: install is allowed but deserves review. warning: stronger safety concern, review before use. dangerous: known-dangerous rows are blocked from default /discover. unaudited: no current safety analysis is available. - `results[].debug_score_breakdown` (object, optional) — Reserved diagnostic score breakdown. Declared in the schema for a future release; v0.8 /discover responses do not emit this field. - `results[].debug_score_breakdown.rrf_score` (number, required) — Reserved (not emitted at v0.8). Reciprocal-rank-fusion base score before multiplicative factors. - `results[].debug_score_breakdown.semantic_rank` (integer, nullable, required) — Reserved (not emitted at v0.8). Semantic-search rank, or null when absent. - `results[].debug_score_breakdown.semantic_score` (number, nullable, required) — Reserved (not emitted at v0.8). Semantic-search score, or null when absent. - `results[].debug_score_breakdown.fts_rank` (integer, nullable, required) — Reserved (not emitted at v0.8). Full-text-search rank, or null when absent. - `results[].debug_score_breakdown.fts_score` (number, nullable, required) — Reserved (not emitted at v0.8). Full-text-search score, or null when absent. - `results[].debug_score_breakdown.trust_factor` (number, required) — Reserved (not emitted at v0.8). Trust multiplier applied during ranking. - `results[].debug_score_breakdown.recency_factor` (number, required) — Reserved (not emitted at v0.8). Recency multiplier applied during ranking. - `results[].debug_score_breakdown.quality_factor` (number, required) — Reserved (not emitted at v0.8). Quality multiplier applied during ranking. - `results[].debug_score_breakdown.safety_factor` (number, required) — Reserved (not emitted at v0.8). Safety multiplier applied during ranking. - `results[].debug_score_breakdown.final_score` (number, required) — Reserved (not emitted at v0.8). Final ranking score after all factors. - `results[].signals` (object, required) — Nested object. - `results[].signals.stars` (integer, optional) — GitHub star count when present on /discover. - `results[].signals.installs` (integer, optional) — Install count signal when present on /discover. - `results[].signals.downloads` (integer, optional) — Download count signal when present on /discover. - `results[].signals.updated_at` (string, optional) — Upstream last-updated date-time when present on /discover. - `results[].signals.indexed_at` (string, required) — ISO date-time when Sigildex last indexed this skill. - `results[].signals.context_cost_tokens` (integer, optional) — Estimated SKILL.md context cost in tokens when present on /discover. - `results[].signals.publisher_metrics` (object, optional) — Nested object. - `results[].signals.publisher_metrics.first_commit_date` (string, optional) — First repository commit date when present on /discover. - `results[].signals.publisher_metrics.repo_age_days` (integer, optional) — Repository age in days when present on /discover. - `results[].signals.publisher_metrics.contributor_count` (integer, optional) — Repository contributor count when present on /discover. - `results[].signals.publisher_metrics.release_count` (integer, optional) — Repository release count when present on /discover. - `results[].signals.publisher_metrics.archived` (boolean, optional) — Whether the repository is archived when present on /discover. - `results[].signals.publisher_metrics.license` (string, optional) — Repository license identifier or name when present on /discover. - `results[].signals.publisher_metrics.trust_score` (number, optional) — Publisher/repository trust score when present on /discover. - `meta` (object, required) — Result metadata after post-filtering. Responses may contain fewer than limit results when dangerous rows are omitted. - `meta.total_results` (integer, required) — Rows returned after post-filtering, including dangerous-row exclusion. May be fewer than limit. - `meta.limit` (integer, required) — Effective result limit applied to the request. - `meta.index_status` (string, enum "ok" | "degraded" | "rebuilding", required) — Index freshness state for /discover. ok: index is healthy. degraded: freshness checks failed or timed out, but search is still served. rebuilding: rebuild is in progress. ## 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. `/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`. The `source.content_hash` and `safety.audited_content_hash` fields follow the [Verification](https://sigildex.ai/docs/identity) hash recipe and pin/verify contract. ### Request example #### curl ```bash curl -X POST https://sigildex.ai/inspect \ -H "Content-Type: application/json" \ -d '{"skill_id":"","query_id":""}' ``` #### Python ```python import requests response = requests.post( "https://sigildex.ai/inspect", json={ "skill_id": "", "query_id": "" }, ) response.raise_for_status() print(response.json()) ``` #### TypeScript ```typescript const response = await fetch("https://sigildex.ai/inspect", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ "skill_id": "", "query_id": "" }), }); if (!response.ok) throw new Error(await response.text()); console.log(await response.json()); ``` ### Request parameters - `skill_id` (string, optional) — Skill UUID from /discover results. - `source_url` (string, optional) — Human-browsable SKILL.md source URL. - `content_hash` (string, optional) — Stored content hash in sha256: form; bare hex is accepted by the API. - `query_id` (string, optional) — query_id from the /discover call that found this skill; valid for free /inspect within the 1h TTL and 5-inspect cap. - `oneOf[skill_id]` (oneOf, required) — oneOf arm: oneOf[skill_id] - `oneOf[skill_id].skill_id` (string, required) — Skill UUID from /discover results. - `oneOf[skill_id].source_url` (string, optional) — Human-browsable SKILL.md source URL. - `oneOf[skill_id].content_hash` (string, optional) — Stored content hash in sha256: form; bare hex is accepted by the API. - `oneOf[skill_id].query_id` (string, optional) — query_id from the /discover call that found this skill; valid for free /inspect within the 1h TTL and 5-inspect cap. - `oneOf[source_url]` (oneOf, required) — oneOf arm: oneOf[source_url] - `oneOf[source_url].skill_id` (string, optional) — Skill UUID from /discover results. - `oneOf[source_url].source_url` (string, required) — Human-browsable SKILL.md source URL. - `oneOf[source_url].content_hash` (string, optional) — Stored content hash in sha256: form; bare hex is accepted by the API. - `oneOf[source_url].query_id` (string, optional) — query_id from the /discover call that found this skill; valid for free /inspect within the 1h TTL and 5-inspect cap. - `oneOf[content_hash]` (oneOf, required) — oneOf arm: oneOf[content_hash] - `oneOf[content_hash].skill_id` (string, optional) — Skill UUID from /discover results. - `oneOf[content_hash].source_url` (string, optional) — Human-browsable SKILL.md source URL. - `oneOf[content_hash].content_hash` (string, required) — Stored content hash in sha256: form; bare hex is accepted by the API. - `oneOf[content_hash].query_id` (string, optional) — query_id from the /discover call that found this skill; valid for free /inspect within the 1h TTL and 5-inspect cap. ### Response example ```json { "skill_id": "550e8400-e29b-41d4-a716-446655440000", "name": "pdf-ocr", "description": "Extract text from scanned PDFs.", "content": "# PDF OCR\n\nUse this skill to extract text from scanned PDFs.", "source": { "registry": "github", "url": "https://github.com/org/repo/blob/main/SKILL.md", "raw_url": "https://raw.githubusercontent.com/org/repo/main/SKILL.md", "content_hash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "indexed_at": "2026-06-12T00:00:00.000Z", "commit_sha": "abc123", "tree_url_at_commit": "https://github.com/org/repo/tree/abc123" }, "install": { "manager": "skills", "package": "github:org/repo", "skill": "pdf-ocr", "args": [], "command": "skills install github:org/repo --skill pdf-ocr", "requires_confirmation": true }, "manifest": { "files": [ { "path": "SKILL.md", "type": "instructions", "language": null, "size_bytes": 1234, "sha256": "sha256:..." } ], "package_hash": "sha256:...", "summary": { "total_files": 1, "total_bytes": 1234, "has_scripts": false, "has_assets": false, "omitted_count": 0, "truncated": false, "truncation_reason": null } }, "install_options": [ { "target": "codex_user", "destination": "~/.codex/skills/pdf-ocr", "command": "mkdir -p ~/.codex/skills && git clone https://github.com/org/repo ~/.codex/skills/pdf-ocr" } ], "publisher": "org", "publisher_type": null, "publisher_verified": false, "audit_status": "pass", "audit_details": null, "skill_type": "capability", "quality_flags": [], "selection_flags": [], "cluster_id": null, "capabilities": { "declared": null, "inferred": [ "pdf", "ocr" ] }, "verification_level": "tested", "safety": { "status": "safe", "recommended_action": "safe_to_install", "executes_code": false, "safety_flags": [], "score": 0.98, "analyzed_at": "2026-06-12T00:00:00.000Z", "safety_version": 1, "audited_content_hash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "freshness": "fresh", "scope": "Verdict covers SKILL.md content and metadata signals only — not bundled scripts, dependencies, or install-time behavior." }, "pin": { "skill_id": "550e8400-e29b-41d4-a716-446655440000", "source_url": "https://github.com/org/repo/blob/main/SKILL.md", "content_hash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "commit_sha": "abc123", "verdict": "safe", "audited_at": "2026-06-12T00:00:00.000Z" }, "signals": { "stars": 42, "installs": null, "downloads": null, "updated_at": null, "indexed_at": "2026-06-12T00:00:00.000Z", "context_cost_tokens": 620, "publisher_metrics": null, "behavioral": null, "measured_utility": null, "stack_relations": null }, "query_id": "q_7f3a2b1c9e4d" } ``` ### Response fields - `skill_id` (string, required) — Skill UUID. - `name` (string, required) — Skill display name. - `description` (string, required) — Short skill description. - `content` (string, required) — Full SKILL.md content. - `source` (object, required) — Nested object. - `source.registry` (string, enum "github" | "clawhub", required) — Registry where Sigildex indexed the skill. github: GitHub-hosted SKILL.md row. clawhub: legacy ClawHub row. - `source.url` (string, required) — Human-browsable source URL. - `source.raw_url` (string, nullable, required) — Canonical raw URL when available. - `source.content_hash` (string, nullable, required) — sha256: hash for the indexed content, or null for legacy rows. - `source.indexed_at` (string, required) — ISO date-time when Sigildex last indexed this skill. - `source.commit_sha` (string, nullable, required) — Git commit captured at crawl time, when available. - `source.tree_url_at_commit` (string, nullable, required) — Tree URL pinned to commit_sha, when available. - `install` (object, required) — Nested object. - `install.manager` (string, enum "skills" | "manual", required) — Installer family. skills: install with the skills CLI. manual: manual install instructions. - `install.package` (string, required) — Package or source identifier to install. - `install.skill` (string, nullable, required) — Skill name or package-local skill path, or null when not applicable. - `install.args` (array, required) — Installer arguments; v0.8 returns an empty array. - `install.args[]` (string, required) — Installer argument. - `install.command` (string, required) — Rendered command. Does not include --yes. - `install.requires_confirmation` (boolean, required) — Whether autonomous agents should obtain user confirmation before running the command. - `manifest` (object, nullable, required) — Nested object. - `manifest.files` (array, required) — Included files in the skill package manifest. - `manifest.files[]` (object, required) — Included files in the skill package manifest. - `manifest.files[].path` (string, required) — Repo-relative file path in the skill package. - `manifest.files[].type` (string, enum "instructions" | "script" | "config" | "reference" | "asset" | "other", required) — Manifest file classification. instructions: SKILL.md or instruction file. script: executable/script file. config: configuration file. reference: reference document. asset: binary or media asset. other: uncategorized file. - `manifest.files[].language` (string, optional) — Programming language for script files when detected. - `manifest.files[].size_bytes` (integer, required) — File size in bytes. - `manifest.files[].sha256` (string, nullable, required) — sha256: blob hash for instructions, script, and config files; null for other file classes at v0.8. - `manifest.package_hash` (string, required) — Stable sha256 hash over the full path/git-content set. - `manifest.summary` (object, required) — Nested object. - `manifest.summary.total_files` (integer, required) — Full file count before any manifest truncation. - `manifest.summary.total_bytes` (integer, required) — Sum of size_bytes for included manifest files. - `manifest.summary.has_scripts` (boolean, required) — Whether the included manifest files contain scripts. - `manifest.summary.has_assets` (boolean, required) — Whether the included manifest files contain assets. - `manifest.summary.omitted_count` (integer, required) — Number of files omitted by manifest truncation; 0 when not truncated. - `manifest.summary.truncated` (boolean, required) — Whether the original file list exceeded the manifest file cap. - `manifest.summary.truncation_reason` (string, nullable, enum "max_files" | null, required) — Why the manifest was truncated. max_files: file-count cap was applied. null: manifest was not truncated. - `install_options` (array, required) — Nested object. - `install_options[]` (object, required) — Nested object. - `install_options[].target` (string, enum "claude_code_user" | "claude_code_project" | "codex_user", required) — Runtime destination for a commit-pinned install option. claude_code_user: Claude Code user skills directory. claude_code_project: Claude Code project skills directory. codex_user: Codex user skills directory. - `install_options[].destination` (string, required) — Runtime-specific destination directory for the install. - `install_options[].command` (string, required) — Multi-line shell command. Display verbatim. - `publisher` (string, required) — Publisher display name, or 'unknown' when absent. - `publisher_type` (string, nullable, required) — Publisher type when known, or null. - `publisher_verified` (boolean, required) — Whether the publisher has a verified signal. - `audit_status` (string, enum "pass" | "warn" | "fail" | "unaudited", required) — Third-party audit aggregate. pass: no audit concern. warn: audit warning. fail: audit failure. unaudited: no third-party audit result. - `audit_details` (object, nullable, required) — Third-party audit details keyed by auditor name, or null when unavailable. - `audit_details{}` (object, optional) — Third-party audit details keyed by auditor name, or null when unavailable. - `audit_details{}.risk` (string, required) — Third-party audit risk label. - `audit_details{}.alerts` (integer, optional) — Number of audit alerts reported by the auditor. - `audit_details{}.score` (number, optional) — Auditor-provided numeric score. - `audit_details{}.analyzed_at` (string, required) — ISO date-time when the auditor produced this detail row. - `skill_type` (string, nullable, enum "capability" | "discipline" | "workflow" | "domain" | "document_tool" | "meta_catalog" | null, required) — Optional skill taxonomy. capability: concrete agent capability. discipline: practice area. workflow: multi-step workflow. domain: domain-specific knowledge. document_tool: document-processing tool. meta_catalog: catalog or index skill. null: not classified. - `quality_flags` (array, nullable, required) — Quality flags when assessed; [] means assessed and clean; null means not assessed. - `quality_flags[]` (string, required) — Quality flags when assessed; [] means assessed and clean; null means not assessed. - `selection_flags` (array, required) — Selection-critical claim flags detected from the skill name and description. - `selection_flags[]` (string, required) — Selection-critical claim flags detected from the skill name and description. - `cluster_id` (string, nullable, required) — Cluster identifier for related skills, or null when absent. - `capabilities` (object, required) — Nested object. - `capabilities.declared` (array, nullable, required) — Publisher-declared capabilities, or null when absent. - `capabilities.declared[]` (string, required) — Publisher-declared capabilities, or null when absent. - `capabilities.inferred` (array, nullable, required) — Sigildex-inferred capabilities for the current content hash, or null when absent or stale. - `capabilities.inferred[]` (string, required) — Sigildex-inferred capabilities for the current content hash, or null when absent or stale. - `verification_level` (string, enum "unverified" | "declared" | "tested" | "formal", required) — Evidence level for the skill metadata. unverified: no independent verification. declared: publisher-declared only. tested: tested by Sigildex or an upstream source. formal: formal verification evidence. - `safety` (object, required) — Nested object. - `safety.status` (string, enum "safe" | "caution" | "warning" | "dangerous" | "unaudited", required) — Safety verdict from Sigildex analysis. safe: no known safety concern. caution: install is allowed but deserves review. warning: stronger safety concern, review before use. dangerous: known-dangerous rows are blocked from default /discover. unaudited: no current safety analysis is available. - `safety.recommended_action` (string, enum "safe_to_install" | "review_before_install" | "block", required) — Agent-facing install recommendation derived from safety status and executes_code. safe_to_install: safe status and no registry-reported code execution — still check manifest.summary.has_scripts on /inspect before install. review_before_install: human or policy review recommended before install. block: do not install. - `safety.executes_code` (boolean, required) — Presence-only code-execution flag sourced from registry metadata; at v0.8 it is populated only for rows from the frozen ClawHub snapshot, so GitHub rows report false even when the bundle contains scripts. Do not treat false as no-bundled-scripts — check manifest.summary.has_scripts on /inspect for bundle evidence. Script contents are never analyzed. - `safety.safety_flags` (array, required) — Full safety findings array. - `safety.safety_flags[]` (string, required) — Full safety findings array. - `safety.score` (number, required) — Composite safety score. - `safety.analyzed_at` (string, nullable, required) — ISO date-time when the safety analysis ran, or null if unaudited. - `safety.safety_version` (integer, nullable, required) — Safety scanner version that produced the verdict, or null if unaudited. - `safety.audited_content_hash` (string, nullable, required) — sha256: hash the safety verdict was computed against. - `safety.freshness` (string, enum "never_audited" | "stale_unverifiable" | "stale_content_drift" | "stale_scanner_version" | "fresh", required) — Whether the safety verdict still matches the indexed content. never_audited: no audit exists. stale_unverifiable: freshness cannot be checked. stale_content_drift: content hash differs from the audited hash. stale_scanner_version: scanner/version changed since audit. fresh: verdict matches the current content and scanner. - `safety.scope` (string, const "Verdict covers SKILL.md content and metadata signals only — not bundled scripts, dependencies, or install-time behavior.", required) — Fixed scope statement for the safety verdict. - `pin` (object, required) — Nested object. - `pin.skill_id` (string, required) — Skill UUID to pin. - `pin.source_url` (string, required) — Human-browsable source URL to pin. - `pin.content_hash` (string, nullable, required) — sha256: content hash to pin, or null for legacy rows. - `pin.commit_sha` (string, nullable, required) — Git commit SHA captured at crawl time, or null when unavailable. - `pin.verdict` (string, enum "safe" | "caution" | "warning" | "dangerous" | "unaudited", required) — Safety verdict from Sigildex analysis. safe: no known safety concern. caution: install is allowed but deserves review. warning: stronger safety concern, review before use. dangerous: known-dangerous rows are blocked from default /discover. unaudited: no current safety analysis is available. - `pin.audited_at` (string, nullable, required) — ISO date-time for the pinned safety verdict, or null if unaudited. - `signals` (object, required) — Nested object. - `signals.stars` (integer, nullable, required) — GitHub star count, or null when unavailable. - `signals.installs` (integer, nullable, required) — Install count signal, or null when unavailable. - `signals.downloads` (integer, nullable, required) — Download count signal, or null when unavailable. - `signals.updated_at` (string, nullable, required) — Upstream last-updated date-time, or null when unavailable. - `signals.indexed_at` (string, required) — ISO date-time when Sigildex last indexed this skill. - `signals.context_cost_tokens` (integer, nullable, required) — Estimated SKILL.md context cost in tokens, or null when unavailable or stale. - `signals.publisher_metrics` (object, nullable, required) — Publisher and repository trust metrics, or null when unavailable. - `signals.publisher_metrics.first_commit_date` (string, nullable, required) — First repository commit date, or null when unknown. - `signals.publisher_metrics.repo_age_days` (integer, nullable, required) — Repository age in days, or null when unknown. - `signals.publisher_metrics.contributor_count` (integer, nullable, required) — Number of repository contributors, or null when unknown. - `signals.publisher_metrics.release_count` (integer, nullable, required) — Number of repository releases, or null when unknown. - `signals.publisher_metrics.archived` (boolean, nullable, required) — Whether the repository is archived, or null when unknown. - `signals.publisher_metrics.license` (string, nullable, required) — Repository license identifier or name, or null when unknown. - `signals.publisher_metrics.trust_score` (number, nullable, required) — Publisher/repository trust score, or null when unavailable. - `signals.behavioral` (null, nullable, required) — Reserved; always null at v0.8. - `signals.measured_utility` (null, nullable, required) — Reserved; always null at v0.8. - `signals.stack_relations` (null, nullable, required) — Reserved; always null at v0.8. - `query_id` (string, nullable, required) — query_id used for this inspect response, or null when paid or unavailable. ## GET /verify Free verdict lookup for content you already hold. Pass `content_hash`, `source_url`, or both: `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`. ### Request example #### curl ```bash curl "https://sigildex.ai/verify?content_hash=sha256:" curl "https://sigildex.ai/verify?source_url=https%3A%2F%2Fgithub.com%2Forg%2Frepo%2Fblob%2Fmain%2FSKILL.md&content_hash=sha256:" ``` #### Python ```python import requests params = { "content_hash": "sha256:" } response = requests.get("https://sigildex.ai/verify", params=params) response.raise_for_status() print(response.json()) ``` #### TypeScript ```typescript const params = new URLSearchParams({"content_hash":"sha256:"}); const response = await fetch(`https://sigildex.ai/verify?${params}`); if (!response.ok) throw new Error(await response.text()); console.log(await response.json()); ``` ### Request parameters - `source_url` (string, optional) — Human-browsable SKILL.md source URL to verify. - `content_hash` (string, optional) — Stored content hash in sha256: form; bare hex is accepted by the API. ### Response example ```json { "matched": true, "matched_by": "content_hash", "skill": { "skill_id": "550e8400-e29b-41d4-a716-446655440000", "source_url": "https://github.com/org/repo/blob/main/SKILL.md", "name": "pdf-ocr" }, "match": { "your_hash_matches_audited": true, "current_content_hash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" }, "safety": { "status": "safe", "recommended_action": "safe_to_install", "executes_code": false, "safety_flags": [], "score": 0.98, "analyzed_at": "2026-06-12T00:00:00.000Z", "safety_version": 1, "audited_content_hash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "freshness": "fresh", "scope": "Verdict covers SKILL.md content and metadata signals only — not bundled scripts, dependencies, or install-time behavior." } } ``` ### Response fields - `oneOf[VerifyHitResponse]` (oneOf, required) — oneOf arm: oneOf[VerifyHitResponse] - `oneOf[VerifyHitResponse].matched` (boolean, const true, required) — Constant true for a verification hit. - `oneOf[VerifyHitResponse].matched_by` (string, enum "content_hash" | "source_url" | "both", required) — Selector that matched an indexed skill. content_hash: matched by content hash. source_url: matched by source URL. both: both supplied selectors matched the same indexed skill. - `oneOf[VerifyHitResponse].skill` (object, required) — Nested object. - `oneOf[VerifyHitResponse].skill.skill_id` (string, required) — Matched skill UUID. - `oneOf[VerifyHitResponse].skill.source_url` (string, required) — Matched skill source URL. - `oneOf[VerifyHitResponse].skill.name` (string, required) — Matched skill display name. - `oneOf[VerifyHitResponse].match` (object, required) — Nested object. - `oneOf[VerifyHitResponse].match.your_hash_matches_audited` (boolean, nullable, required) — Whether the supplied content_hash matches the current indexed content hash (current_content_hash); null when no content_hash was supplied. Compare safety.audited_content_hash separately to check audit freshness. - `oneOf[VerifyHitResponse].match.current_content_hash` (string, nullable, required) — Current indexed sha256: content hash, or null when unavailable. - `oneOf[VerifyHitResponse].safety` (object, required) — Nested object. - `oneOf[VerifyHitResponse].safety.status` (string, enum "safe" | "caution" | "warning" | "dangerous" | "unaudited", required) — Safety verdict from Sigildex analysis. safe: no known safety concern. caution: install is allowed but deserves review. warning: stronger safety concern, review before use. dangerous: known-dangerous rows are blocked from default /discover. unaudited: no current safety analysis is available. - `oneOf[VerifyHitResponse].safety.recommended_action` (string, enum "safe_to_install" | "review_before_install" | "block", required) — Agent-facing install recommendation derived from safety status and executes_code. safe_to_install: safe status and no registry-reported code execution — still check manifest.summary.has_scripts on /inspect before install. review_before_install: human or policy review recommended before install. block: do not install. - `oneOf[VerifyHitResponse].safety.executes_code` (boolean, required) — Presence-only code-execution flag sourced from registry metadata; at v0.8 it is populated only for rows from the frozen ClawHub snapshot, so GitHub rows report false even when the bundle contains scripts. Do not treat false as no-bundled-scripts — check manifest.summary.has_scripts on /inspect for bundle evidence. Script contents are never analyzed. - `oneOf[VerifyHitResponse].safety.safety_flags` (array, required) — Full safety findings array. - `oneOf[VerifyHitResponse].safety.safety_flags[]` (string, required) — Full safety findings array. - `oneOf[VerifyHitResponse].safety.score` (number, required) — Composite safety score. - `oneOf[VerifyHitResponse].safety.analyzed_at` (string, nullable, required) — ISO date-time when the safety analysis ran, or null if unaudited. - `oneOf[VerifyHitResponse].safety.safety_version` (integer, nullable, required) — Safety scanner version that produced the verdict, or null if unaudited. - `oneOf[VerifyHitResponse].safety.audited_content_hash` (string, nullable, required) — sha256: hash the safety verdict was computed against. - `oneOf[VerifyHitResponse].safety.freshness` (string, enum "never_audited" | "stale_unverifiable" | "stale_content_drift" | "stale_scanner_version" | "fresh", required) — Whether the safety verdict still matches the indexed content. never_audited: no audit exists. stale_unverifiable: freshness cannot be checked. stale_content_drift: content hash differs from the audited hash. stale_scanner_version: scanner/version changed since audit. fresh: verdict matches the current content and scanner. - `oneOf[VerifyHitResponse].safety.scope` (string, const "Verdict covers SKILL.md content and metadata signals only — not bundled scripts, dependencies, or install-time behavior.", required) — Fixed scope statement for the safety verdict. - `oneOf[VerifyMissResponse]` (oneOf, required) — oneOf arm: oneOf[VerifyMissResponse] - `oneOf[VerifyMissResponse].matched` (boolean, const false, required) — Constant false for a verification miss. - `oneOf[VerifyMissResponse].verification` (string, const "unknown", required) — Constant miss marker; the supplied selector did not resolve to an indexed skill. ## GET /health No payment and no rate limit. Returns `status`, `version`, `uptime_seconds`, `index_fresh`, `skills_indexed`, and descriptor `links`. ### Request example #### curl ```bash curl "https://sigildex.ai/health" ``` #### Python ```python import requests params = {} response = requests.get("https://sigildex.ai/health", params=params) response.raise_for_status() print(response.json()) ``` #### TypeScript ```typescript const params = new URLSearchParams({}); const response = await fetch(`https://sigildex.ai/health?${params}`); if (!response.ok) throw new Error(await response.text()); console.log(await response.json()); ``` ### Request parameters - No request parameters. ### Response example ```json { "status": "ok", "version": "0.8.0", "uptime_seconds": 86400, "index_fresh": true, "skills_indexed": 123456, "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" } } ``` ### Response fields - `status` (string, enum "ok" | "degraded" | "error", required) — Health status. ok: service and index freshness are healthy. degraded: service is up but index freshness is degraded. error: health computation failed. - `version` (string, required) — Sigildex API version. - `uptime_seconds` (integer, required) — Process uptime in seconds. - `index_fresh` (boolean, required) — Whether default-corpus freshness checks are currently passing. - `skills_indexed` (integer, required) — Default-corpus skill count; 0 on the health error path. The example value is illustrative; call GET /health for the live count. - `links` (object, required) — Nested object. - `links.openapi` (string, required) — OpenAPI descriptor URL. - `links.x402` (string, required) — x402 payment descriptor URL. - `links.mcp` (string, required) — MCP descriptor URL. - `links.docs` (string, required) — Agent-readable docs index URL. - `links.support` (string, required) — Human documentation URL. ## MCP tools Text fallbacks include `Safety: - `. Structured content mirrors the REST response plus MCP-only `version`. ### discover_skills Mirrors `POST /discover`. #### Input fields - `query` (string, required) — Natural language description of the skill you need, e.g. 'PDF text extraction with OCR' - `limit` (number, optional) — Maximum number of results to return (default 10) - `source` (string, enum "main" | "github", optional) — Filter by source registry. Default 'main' returns the curated default corpus (today: agent-skill SKILL.md repos and other leading sources). 'github' is the explicit registry alias; functionally identical today, preserved for forward-compatibility as the curated default expands. - `rationale` (string, optional) — Why you're searching — describe the task or workflow, not just the user request. Good: 'building a file-upload utility', 'need OCR for scanned invoices'. Avoid: 'the user wants X' (your task context is more useful than user phrasing). ≤200 chars. ### inspect_skill Mirrors `POST /inspect`. #### Input fields - `source_url` (string, optional) — Human-browsable SKILL.md source URL to resolve before payment. - `content_hash` (string, optional) — Stored sha256 content hash (sha256: accepted) to resolve before payment. - `skill_id` (string, optional) — Skill UUID from discover_skills results (results[].skill_id). - `query_id` (string, optional) — query_id from the discover_skills call that found this skill (1h TTL). ### verify_skill Mirrors `GET /verify`. #### Input fields - `content_hash` (string, optional) — Stored sha256 content hash (sha256: accepted). Provide content_hash, source_url, or both for a cross-check. - `source_url` (string, optional) — Human-browsable SKILL.md source URL. Provide content_hash, source_url, or both for a cross-check. ## CLI ```bash npx @sigildex/cli search "PDF text extraction" --limit 3 --json npx @sigildex/cli inspect --query-id --json npx @sigildex/cli verify --content-hash sha256: --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` with an x402 challenge; rate limiting returns `RATE_LIMITED`. If x402 payments are temporarily disabled service-side, free-tier exhaustion returns `RATE_LIMITED` with HTTP 402 and no payment challenge — branch on the error code, not the HTTP status. | Code | HTTP status(es) | Retry behavior | is_retriable | When seen | |---|---:|---|---|---| | `RATE_LIMITED` | 429, 402 | retry_after_seconds is populated when a rate-limit bucket can provide a reset hint. | true | Per-IP free-tier, /inspect query_id cap, /inspect unresolved-selector guard, or /verify lookup bucket is exhausted. If x402 payments are temporarily disabled service-side, free-tier exhaustion returns this code with HTTP 402 instead of PAYMENT_REQUIRED. | | `PAYMENT_REQUIRED` | 402 | No retry_after_seconds; satisfy the x402 payment challenge or wait for the free-tier window. | true | Free discovery-workflow budget is exhausted and no supported payment proof was supplied. | | `PAYMENT_FAILED` | 402, 400 | No retry_after_seconds; retry after fixing or replacing the payment proof. | true | The x402 facilitator rejected the supplied payment proof or returned a non-5xx payment error. The facilitator-reported non-5xx HTTP status is preserved, so statuses other than 402/400 are possible; branch on the code, not the status. | | `PAYMENT_UNAVAILABLE` | 503, 500 | retry_after_seconds is 30 on known payment-facilitator outage paths; otherwise retry with backoff. | true | Payment facilitator, payment network, or payment configuration is temporarily unavailable. Upstream 5xx statuses are preserved, so statuses other than 503/500 are possible; branch on the code, not the status. | | `PROTOCOL_UNSUPPORTED` | 501 | Do not retry with the same payment protocol. | false | An unsupported payment protocol such as MPP is supplied where x402 is required. | | `INVALID_REQUEST` | 400, 413 | No retry_after_seconds; fix the request shape before retrying. | false | Request JSON, selector shape, query parameter shape, or body validation failed. Body-parser 4xx errors are also preserved under INVALID_REQUEST, so the HTTP status may be any parser-provided 4xx such as 413. | | `INVALID_SKILL_ID` | 400 | No retry_after_seconds; provide a valid 8-4-4-4-12 hex UUID. | false | skill_id is present but does not match the accepted UUID text format. | | `INVALID_QUERY_ID` | 400 | No retry_after_seconds; run /discover again or use the matching skill_id. | false | query_id is expired, unknown, mismatched to the requested skill, or malformed for /inspect. | | `NOT_FOUND` | 404 | No retry_after_seconds; choose another selector or skill_id. | false | The selected skill cannot be resolved in the public default corpus. | | `DEPENDENCY_UNAVAILABLE` | 503 | retry_after_seconds is populated when the upstream dependency supplies a retry-after hint. | true | The upstream embedding/search dependency is rate-limiting Sigildex or returning a 5xx. | | `INTERNAL_ERROR` | 500 | No retry_after_seconds; retry with normal exponential backoff. | true | An unexpected server error escaped the typed ApiError paths. | ## Rate limits Free tier: 50 discovery workflows per day per IP, resets midnight UTC. `/inspect` is free with a valid `query_id` (up to 5 per id within the 1h TTL). Beyond the quota, $0.002 per workflow via x402 — see [Payments](https://sigildex.ai/docs/payments). Quota state is reported in rate-limit response headers on discovery responses. --- ## Mirror: /docs/payments.md # Payments > x402 setup for paid discovery workflows. You do not need payment setup for the free tier, `GET /health`, descriptors, docs, or `GET /verify`. ## How x402 works x402 turns HTTP's long-reserved `402 Payment Required` status into a working payment flow: the API quotes a price, your agent pays in-band, and the request completes. No account, no API key, no checkout page. **No blockchain knowledge required** — the CLI and x402 client libraries handle the full payment exchange automatically. Payments are in USDC — a stablecoin pegged 1:1 to the US dollar — on the Base network, so prices are dollar prices: $0.002 per discovery workflow. ### The automatic flow 1. Your agent calls `POST /discover` as normal. 2. If the free tier is exhausted, Sigildex responds `402 Payment Required` — the x402 challenge rides in the `PAYMENT-REQUIRED` response header, and the machine-readable terms (price, asset, network, pay-to address) are published at `/.well-known/x402.json`. 3. Your x402 client signs a USDC payment authorization for the quoted price and retries the same request with the `payment-signature` header. 4. Sigildex verifies the payment, serves the response, and settles on Base. Failed application responses are never settled — you do not pay for errors. ```text agent sigildex base (USDC) | | | |-- 1 POST /discover ------->| | |<- 2 402 + requirements ----| | |-- 3 retry + payment-signature -->| | | |-- 4 settle $0.002 ---->| |<- 4 200 ranked results ----| | ``` ### What you need - **Nothing**, for the free tier (50 discovery workflows per day per IP), `GET /verify`, `GET /health`, descriptors, and docs. - **For paid discovery:** an EVM wallet key holding USDC on Base — `SIGILDEX_WALLET_KEY` for the CLI, or an x402 client library in your application. - **Machine-readable terms:** [`/.well-known/x402.json`](https://sigildex.ai/.well-known/x402.json). Sigildex settles through the Coinbase Developer Platform facilitator; the open protocol lives at [x402.org](https://www.x402.org). ## Pricing - 50 discovery workflows per day per IP are free. - After the free tier, discovery workflows cost $0.002 USDC on Base. - A workflow is one `/discover` call plus up to 5 free `/inspect` calls using the returned `query_id`. - `/verify` is free and never returns a payment challenge. ## Auto-pay ```bash export SIGILDEX_WALLET_KEY= npx @sigildex/cli search "browser automation" --json ``` The CLI uses x402 to sign and retry paid requests when a wallet key is configured. For application integrations, fetch `/.well-known/x402.json` and handle the payment challenge returned by paid endpoints. ## Headers Paid requests use `payment-signature`. Responses include `X-Sigildex-Version` and `X-Request-Id`; discovery responses also include rate-limit headers. ## Errors `PAYMENT_REQUIRED` means the free discovery tier is exhausted and a valid payment is needed. `PAYMENT_FAILED` means payment verification failed. `PAYMENT_UNAVAILABLE` means the payment system is temporarily unavailable. No settlement occurs for failed application responses. --- ## Mirror: /docs/identity.md # Verification > Public contract for stable skill IDs, removed rows, and content hashes. These fields are produced by the endpoints in the [Reference](https://sigildex.ai/docs/api): see [`/inspect`](https://sigildex.ai/docs/api#post-inspect) for `source.content_hash`, `safety.audited_content_hash`, and `pin`, and [`/verify`](https://sigildex.ai/docs/api#get-verify) for the lookup response. ## Stable skill IDs `skill_id` is the stable identifier Sigildex assigns to a skill row. When the same source is re-indexed, the existing UUID is carried forward. A skill can move through many scans and safety verdicts without changing `skill_id`. If a row is no longer in the served index, `/inspect` returns `404 NOT_FOUND`. `/verify` is an oracle-style lookup: for removed or unknown content it returns HTTP 200 with `{"matched": false, "verification": "unknown"}`. ## Content hash recipe All public hashes use lowercase `sha256:`. - GitHub rows: `content_hash` is the SHA-256 digest of the raw SKILL.md file bytes at the pinned commit, including frontmatter. Use the bytes as fetched; do not trim, normalize newlines, or parse frontmatter before hashing. - Rows from the frozen ClawHub snapshot: `content_hash` is the SHA-256 digest of the served SKILL.md content returned by Sigildex. ## Reference snippet ```js import { createHash } from "node:crypto"; export function sigildexContentHash(bytes) { return "sha256:" + createHash("sha256").update(bytes).digest("hex"); } ``` For GitHub, pass the raw file bytes from the pinned commit. For rows from the frozen ClawHub snapshot, pass the served content bytes exactly as returned. ## Pin and verify `/inspect.pin` returns `{skill_id, source_url, content_hash, commit_sha, verdict, audited_at}`. Store that object next to the installed skill. On load or in CI, call `/verify` with `content_hash`, `source_url`, or both. If both are supplied, the source URL is resolved first and the hash is checked against the matched row. --- ## Mirror: /docs/index.md # Sigildex Documentation > Quickstart, REST + MCP + CLI reference, and x402 payments setup. Each page has a Markdown mirror at the same path with a `.md` suffix for agent extraction. Sigildex is a skill discovery API for coding agents. One natural-language query returns ranked, inspectable results from agent-skill SKILL.md repos and other leading sources. No accounts, no API keys, no SDK install required. 50 discovery workflows free per day per IP; pay-per-workflow in USDC on Base via x402 beyond. ## Getting started - [Quickstart](https://sigildex.ai/docs/quickstart.md): Pick your integration — MCP, REST, or CLI. Same index, same ranking. - [API Reference](https://sigildex.ai/docs/api.md): REST endpoints, MCP tools, CLI commands, error codes, rate limits. ## Concepts - [Payments](https://sigildex.ai/docs/payments.md): x402 micropayments setup, network details, headers, troubleshooting. - [Verification](https://sigildex.ai/docs/identity.md): Stable skill IDs, the content-hash recipe, and the pin / verify trust contract. ## Agent-readable manifests - [`/llms.txt`](https://sigildex.ai/llms.txt): Single-file overview optimized for LLM extraction. - [`/openapi.json`](https://sigildex.ai/openapi.json): Full OpenAPI 3.1 specification. - [`/.well-known/mcp.json`](https://sigildex.ai/.well-known/mcp.json): MCP server discovery descriptor. - [`/.well-known/x402.json`](https://sigildex.ai/.well-known/x402.json): x402 payment descriptor. - [`/SKILL.md`](https://sigildex.ai/SKILL.md): Drop into `.claude/skills/` to teach Claude Code about Sigildex. - [`/CLAUDE.md`](https://sigildex.ai/CLAUDE.md): Project-level Claude integration notes. ## Live status - [`GET /health`](https://sigildex.ai/health): Liveness, version, default-corpus skill count, freshness signal.