Reference

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

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

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.

SIWX verified free tier

Sign once with a wallet for a higher free tier. Fetch GET /auth/siwx/nonce, sign a SIWX/SIWE message for Sigildex on Base, exchange it at POST /auth/siwx, then send Authorization: SIWX <token> on /discover, /inspect, or the MCP HTTP request. Missing SIWX auth stays anonymous. Invalid or expired SIWX auth returns INVALID_AUTH; dependency outages return DEPENDENCY_UNAVAILABLE.

For AI agents: fetch /llms.txt for the surface index, or /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.

GET /auth/siwx/nonce

Start the verified free-tier flow. This endpoint returns a single-use nonce for a wallet sign-in message and consumes the authentication-attempt limiter before the nonce is issued.

Sign once with a wallet for a higher free tier: fetch this nonce, include it in a SIWX/SIWE message for Sigildex on Base, then exchange the signed message at POST /auth/siwx.

Request example

curl "https://sigildex.ai/auth/siwx/nonce"

import requests

params = {}
response = requests.get("https://sigildex.ai/auth/siwx/nonce", params=params)
response.raise_for_status()
print(response.json())

const params = new URLSearchParams({});
const response = await fetch(`https://sigildex.ai/auth/siwx/nonce?${params}`);
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

Request parameters

No request parameters.

Response example

{
  "nonce": "4f9c4f8d9b2e4c0fb8c6c6d9a8f3b2a1"
}

Response fields

nonce

string required Single-use nonce for the SIWX sign-in message. It expires after 5 minutes.

POST /auth/siwx

Finish the verified free-tier flow. Send the signed SIWX/SIWE message and wallet signature; Sigildex verifies the domain, nonce, Base chain binding, and wallet signature before minting a 24-hour SIWX token.

Send the returned token as Authorization: SIWX <token> on /discover, /inspect, or the MCP HTTP request. Missing SIWX auth stays anonymous. Invalid signatures, domains, nonces, replays, or expired tokens return 401 INVALID_AUTH; authentication-attempt throttling returns 429 RATE_LIMITED; identity-store or wallet-verification dependency outages return 503 DEPENDENCY_UNAVAILABLE.

Request example

curl -X POST https://sigildex.ai/auth/siwx \
  -H "Content-Type: application/json" \
  -d '{"message":"sigildex.ai wants you to sign in with your Ethereum account:\n0x742d35Cc6634C0532925a3b844Bc454e4438f44e\n\nURI: https://sigildex.ai\nVersion: 1\nChain ID: 8453\nNonce: 4f9c4f8d9b2e4c0fb8c6c6d9a8f3b2a1","signature":"0x1234abcd"}'

import requests

response = requests.post(
    "https://sigildex.ai/auth/siwx",
    json={
      "message": "sigildex.ai wants you to sign in with your Ethereum account:\n0x742d35Cc6634C0532925a3b844Bc454e4438f44e\n\nURI: https://sigildex.ai\nVersion: 1\nChain ID: 8453\nNonce: 4f9c4f8d9b2e4c0fb8c6c6d9a8f3b2a1",
      "signature": "0x1234abcd"
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://sigildex.ai/auth/siwx", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "message": "sigildex.ai wants you to sign in with your Ethereum account:\n0x742d35Cc6634C0532925a3b844Bc454e4438f44e\n\nURI: https://sigildex.ai\nVersion: 1\nChain ID: 8453\nNonce: 4f9c4f8d9b2e4c0fb8c6c6d9a8f3b2a1",
    "signature": "0x1234abcd"
  }),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

Request parameters

message

string required EIP-4361/SIWE message bound to sigildex.ai, Base mainnet, and the nonce from GET /auth/siwx/nonce.

signature

string required Hex wallet signature over the SIWX message.

Response example

{
  "token": "8f4d9a0f2c7b4e1a9d6c3b0a5f8e2d1c"
}

Response fields

token

string required Opaque 24-hour SIWX bearer token. Send it as Authorization: SIWX <token> for the higher free tier.

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.

Optional: send Authorization: SIWX <token> to use a wallet or allocation free-tier bucket. Missing SIWX auth stays on the anonymous free tier. X-RateLimit-* headers report the principal bucket used by the request.

Request example

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

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())

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 Maximum number of results to return; defaults to 10 and is capped at 30.

rationale

string Why you're searching. Good: 'building a file-upload utility'. Avoid: 'the user wants X'.

filters

object Optional discovery filters applied after the public source alias is resolved.

Nested fields

filters.source

string, enum "main" | "github" 'main' is the curated default corpus. 'github' explicitly asks for GitHub-hosted SKILL.md rows.

filters.min_stars

integer Minimum GitHub star count for returned rows.

filters.updated_after

string Only return rows updated after this ISO date-time.

Response example

{
  "query_id": "q_7f3a2b1c9e4d5a6b8c9d0e1f2a3b4c5d",
  "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 Opaque discovery query identifier used to authorize free /inspect calls for matching skills; present on success; absent only when the entitlement store is briefly unavailable — pay for /inspect or retry.

results

array required Ranked skill results.

Nested fields

results[]

object required Compact v0.9.0 discover result. Null-valued optional keys are omitted.

Nested fields

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.

Nested fields

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.

Nested fields

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 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.

Nested fields

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.9.0 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.

Nested fields

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 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 Only present when assessed; [] means assessed and clean.

Nested fields

results[].quality_flags[]

string Only present when assessed; [] means assessed and clean.

results[].selection_flags

array required Claim flags agents rely on when choosing a skill, detected from the skill name and description.

Nested fields

results[].selection_flags[]

string required Claim flags agents rely on when choosing a skill, detected from the skill name and description.

results[].cluster_id

string Cluster identifier for related skills when present.

results[].score_explanation

object Reserved bucketed score explanation. Declared in the schema for a future release; v0.9.0 /discover responses do not emit this field.

Nested fields

results[].score_explanation.match

object required Nested object.

Nested fields

results[].score_explanation.match.level

string, enum "strong" | "good" | "weak" required Reserved (not emitted at v0.9.0). Match contribution bucket. strong: strongest query match. good: acceptable match. weak: low-confidence match.

results[].score_explanation.trust

object required Nested object.

Nested fields

results[].score_explanation.trust.level

string, enum "high" | "medium" | "low" required Reserved (not emitted at v0.9.0). Trust contribution bucket. high: strong publisher, install, and freshness inputs. medium: mixed inputs. low: weak inputs.

results[].score_explanation.recency

object required Nested object.

Nested fields

results[].score_explanation.recency.level

string, enum "current" | "recent" | "stale" required Reserved (not emitted at v0.9.0). Recency contribution bucket. current: current upstream activity. recent: somewhat recent activity. stale: stale upstream activity.

results[].score_explanation.quality

object required Nested object.

Nested fields

results[].score_explanation.quality.level

string, enum "good" | "ok" | "poor" required Reserved (not emitted at v0.9.0). Quality contribution bucket. good: strong quality signals. ok: acceptable quality. poor: weak quality signals.

results[].score_explanation.safety

object required Nested object.

Nested fields

results[].score_explanation.safety.level

string, enum "safe" | "caution" | "warning" | "dangerous" | "unaudited" required Reserved (not emitted at v0.9.0). 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 Reserved diagnostic score breakdown. Declared in the schema for a future release; v0.9.0 /discover responses do not emit this field.

Nested fields

results[].debug_score_breakdown.rrf_score

number required Reserved (not emitted at v0.9.0). Reciprocal-rank-fusion base score before multiplicative factors.

results[].debug_score_breakdown.semantic_rank

integer, nullable required Reserved (not emitted at v0.9.0). Semantic-search rank, or null when absent.

results[].debug_score_breakdown.semantic_score

number, nullable required Reserved (not emitted at v0.9.0). Semantic-search score, or null when absent.

results[].debug_score_breakdown.fts_rank

integer, nullable required Reserved (not emitted at v0.9.0). Full-text-search rank, or null when absent.

results[].debug_score_breakdown.fts_score

number, nullable required Reserved (not emitted at v0.9.0). Full-text-search score, or null when absent.

results[].debug_score_breakdown.trust_factor

number required Reserved (not emitted at v0.9.0). Trust multiplier applied during ranking.

results[].debug_score_breakdown.recency_factor

number required Reserved (not emitted at v0.9.0). Recency multiplier applied during ranking.

results[].debug_score_breakdown.quality_factor

number required Reserved (not emitted at v0.9.0). Quality multiplier applied during ranking.

results[].debug_score_breakdown.safety_factor

number required Reserved (not emitted at v0.9.0). Safety multiplier applied during ranking.

results[].debug_score_breakdown.final_score

number required Reserved (not emitted at v0.9.0). Final ranking score after all factors.

results[].signals

object required Nested object.

Nested fields

results[].signals.stars

integer GitHub star count when present on /discover.

results[].signals.installs

integer Install count signal when present on /discover.

results[].signals.downloads

integer Download count signal when present on /discover.

results[].signals.updated_at

string 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 Estimated SKILL.md context cost in tokens when present on /discover.

results[].signals.publisher_metrics

object Nested object.

Nested fields

results[].signals.publisher_metrics.first_commit_date

string First repository commit date when present on /discover.

results[].signals.publisher_metrics.repo_age_days

integer Repository age in days when present on /discover.

results[].signals.publisher_metrics.contributor_count

integer Repository contributor count when present on /discover.

results[].signals.publisher_metrics.release_count

integer Repository release count when present on /discover.

results[].signals.publisher_metrics.archived

boolean Whether the repository is archived when present on /discover.

results[].signals.publisher_metrics.license

string Repository license identifier or name when present on /discover.

results[].signals.publisher_metrics.trust_score

number 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.

Nested fields

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.

Optional: send Authorization: SIWX <token> to use a wallet or allocation free-tier bucket before paid fallback. Missing SIWX auth stays on the anonymous or query_id path. X-RateLimit-* headers report the principal bucket used by the request.

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 hash recipe and pin/verify contract.

Request example

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

import requests

response = requests.post(
    "https://sigildex.ai/inspect",
    json={
      "skill_id": "<skill_id>",
      "query_id": "<query_id>"
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://sigildex.ai/inspect", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "skill_id": "<skill_id>",
    "query_id": "<query_id>"
  }),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

Request parameters

skill_id

string Skill UUID from /discover results.

source_url

string Human-browsable SKILL.md source URL.

content_hash

string Stored content hash in sha256:<hex> form; bare hex is accepted by the API.

query_id

string query_id from the /discover call that found this skill; valid for free /inspect within the 1h TTL and 5-inspect cap. Validated semantically (entitlement + cap), not by schema pattern.

oneOf[skill_id]

oneOf required oneOf arm: oneOf[skill_id]

Nested fields

oneOf[skill_id].skill_id

string required Skill UUID from /discover results.

oneOf[skill_id].source_url

string Human-browsable SKILL.md source URL.

oneOf[skill_id].content_hash

string Stored content hash in sha256:<hex> form; bare hex is accepted by the API.

oneOf[skill_id].query_id

string query_id from the /discover call that found this skill; valid for free /inspect within the 1h TTL and 5-inspect cap. Validated semantically (entitlement + cap), not by schema pattern.

oneOf[source_url]

oneOf required oneOf arm: oneOf[source_url]

Nested fields

oneOf[source_url].skill_id

string Skill UUID from /discover results.

oneOf[source_url].source_url

string required Human-browsable SKILL.md source URL.

oneOf[source_url].content_hash

string Stored content hash in sha256:<hex> form; bare hex is accepted by the API.

oneOf[source_url].query_id

string query_id from the /discover call that found this skill; valid for free /inspect within the 1h TTL and 5-inspect cap. Validated semantically (entitlement + cap), not by schema pattern.

oneOf[content_hash]

oneOf required oneOf arm: oneOf[content_hash]

Nested fields

oneOf[content_hash].skill_id

string Skill UUID from /discover results.

oneOf[content_hash].source_url

string Human-browsable SKILL.md source URL.

oneOf[content_hash].content_hash

string required Stored content hash in sha256:<hex> form; bare hex is accepted by the API.

oneOf[content_hash].query_id

string query_id from the /discover call that found this skill; valid for free /inspect within the 1h TTL and 5-inspect cap. Validated semantically (entitlement + cap), not by schema pattern.

Response example

{
  "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_7f3a2b1c9e4d5a6b8c9d0e1f2a3b4c5d"
}

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.

Nested fields

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:<hex> 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.

Nested fields

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.9.0 returns an empty array.

Nested fields

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.

Nested fields

manifest.files

array required Included files in the skill package manifest.

Nested fields

manifest.files[]

object required Included files in the skill package manifest.

Nested fields

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 Programming language for script files when detected.

manifest.files[].size_bytes

integer required File size in bytes.

manifest.files[].sha256

string, nullable required sha256:<hex> blob hash for instructions, script, and config files; null for other file classes at v0.9.0.

manifest.package_hash

string required Stable sha256 hash over the full path/git-content set.

manifest.summary

object required Nested object.

Nested fields

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.

Nested fields

install_options[]

object required Nested object.

Nested fields

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.

Nested fields

audit_details{}

object Third-party audit details keyed by auditor name, or null when unavailable.

Nested fields

audit_details{}.risk

string required Third-party audit risk label.

audit_details{}.alerts

integer Number of audit alerts reported by the auditor.

audit_details{}.score

number 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.

Nested fields

quality_flags[]

string required Quality flags when assessed; [] means assessed and clean; null means not assessed.

selection_flags

array required Claim flags agents rely on when choosing a skill, detected from the skill name and description.

Nested fields

selection_flags[]

string required Claim flags agents rely on when choosing a skill, 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.

Nested fields

capabilities.declared

array, nullable required Publisher-declared capabilities, or null when absent.

Nested fields

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.

Nested fields

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.

Nested fields

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.9.0 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.

Nested fields

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:<hex> 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.

Nested fields

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:<hex> 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.

Nested fields

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.

Nested fields

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.9.0.

signals.measured_utility

null, nullable required Reserved; always null at v0.9.0.

signals.stack_relations

null, nullable required Reserved; always null at v0.9.0.

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 "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>"

import requests

params = {
  "content_hash": "sha256:<hex>"
}
response = requests.get("https://sigildex.ai/verify", params=params)
response.raise_for_status()
print(response.json())

const params = new URLSearchParams({"content_hash":"sha256:<hex>"});
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 Human-browsable SKILL.md source URL to verify.

content_hash

string Stored content hash in sha256:<hex> form; bare hex is accepted by the API.

Response example

{
  "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]

Nested fields

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.

Nested fields

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.

Nested fields

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:<hex> content hash, or null when unavailable.

oneOf[VerifyHitResponse].safety

object required Nested object.

Nested fields

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.9.0 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.

Nested fields

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:<hex> 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]

Nested fields

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 "https://sigildex.ai/health"

import requests

params = {}
response = requests.get("https://sigildex.ai/health", params=params)
response.raise_for_status()
print(response.json())

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

{
  "status": "ok",
  "version": "0.9.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.

Nested fields

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.

GET /.well-known/agent-pricing.json

Free pricing manifest for agents. The free tier is first: anonymous callers get 50 discovery workflows per day, and a workflow includes one ranked skill search plus shortlist review of up to 5 candidates within the 1h query_id TTL. Paid fallback is x402_exact at 0.002 USD per discover_workflow.

Responses use Cache-Control: public, max-age=60.

Request example

curl "https://sigildex.ai/.well-known/agent-pricing.json"

import requests

params = {}
response = requests.get("https://sigildex.ai/.well-known/agent-pricing.json", params=params)
response.raise_for_status()
print(response.json())

const params = new URLSearchParams({});
const response = await fetch(`https://sigildex.ai/.well-known/agent-pricing.json?${params}`);
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

Request parameters

No request parameters.

Response example

{
  "service": "sigildex",
  "pricing_strategy_version": "2026-05-06",
  "billing_modes": [
    "free",
    "x402_exact"
  ],
  "billing_modes_planned": [
    "x402_upto",
    "credits",
    "mpp_spt"
  ],
  "free_tier": {
    "anonymous": {
      "workflows_per_day": 50
    }
  },
  "prices": {
    "discover_workflow": {
      "unit": "workflow",
      "definition": "1 ranked skill search + shortlist review of up to 5 candidates within 1h TTL (1 discover + up to 5 inspect)",
      "usd": "0.002"
    }
  },
  "safety": {
    "inspect_discovered_results_is_free": true,
    "charge_failed_responses": false,
    "max_inspects_per_workflow": 5,
    "query_id_ttl_seconds": 3600
  },
  "spend_controls": {
    "supports_max_cost": false,
    "supports_wallet_delegation": false,
    "supports_receipts": true
  },
  "links": {
    "docs": "https://sigildex.ai/llms.txt",
    "openapi": "https://sigildex.ai/openapi.json",
    "mcp": "https://sigildex.ai/.well-known/mcp.json",
    "x402": "https://sigildex.ai/.well-known/x402.json",
    "pricing_strategy": "https://sigildex.ai/docs/payments",
    "organization": "https://sigildex.ai/about"
  }
}

Response fields

service

string, const "sigildex" required Service identifier; the live pricing manifest returns "sigildex".

pricing_strategy_version

string required Pricing-language version for this manifest; the live descriptor currently returns "2026-05-06".

billing_modes

array required Billing modes live today; the current manifest returns ["free", "x402_exact"].

Nested fields

billing_modes[]

string, enum "free" | "x402_exact" required Live billing mode. "free" is the free tier; "x402_exact" is exact per-workflow payment via x402.

billing_modes_planned

array required Billing modes planned but not live; the current manifest returns ["x402_upto", "credits", "mpp_spt"].

Nested fields

billing_modes_planned[]

string, enum "x402_upto" | "credits" | "mpp_spt" required Planned billing mode. "x402_upto", "credits", and "mpp_spt" are trajectory signals, not live payment rails.

free_tier

object required Nested object.

Nested fields

free_tier.anonymous

object required Nested object.

Nested fields

free_tier.anonymous.workflows_per_day

integer required Anonymous free-tier allowance; the live manifest returns 50 discovery workflows per day per IP.

prices

object required Billable products keyed by product id. "discover_workflow" is live today and always present; additional product keys may appear as new products ship.

Nested fields

prices.discover_workflow

object required The live billable product: one discovery workflow. Always present in the live manifest.

Nested fields

prices.discover_workflow.unit

string required Billable unit for this product; discover_workflow currently uses "workflow".

prices.discover_workflow.definition

string required Human-readable product definition; discover_workflow is "1 ranked skill search + shortlist review of up to 5 candidates within 1h TTL (1 discover + up to 5 inspect)".

prices.discover_workflow.usd

string required USD price string without a leading dollar sign; the default discover_workflow price is "0.002".

prices{}

object Billable product entry keyed by product id.

Nested fields

prices{}.unit

string required Billable unit for this product; discover_workflow currently uses "workflow".

prices{}.definition

string required Human-readable product definition; discover_workflow is "1 ranked skill search + shortlist review of up to 5 candidates within 1h TTL (1 discover + up to 5 inspect)".

prices{}.usd

string required USD price string without a leading dollar sign; the default discover_workflow price is "0.002".

safety

object required Nested object.

Nested fields

safety.inspect_discovered_results_is_free

boolean required Whether inspecting results from a discovery workflow is free when authorized by query_id; the live manifest returns true.

safety.charge_failed_responses

boolean required Whether failed application responses are charged; the live manifest returns false.

safety.max_inspects_per_workflow

integer required Maximum free inspect calls attached to one discovery workflow; the live manifest returns 5.

safety.query_id_ttl_seconds

integer required Lifetime of the query_id entitlement in seconds; the live manifest returns 3600.

spend_controls

object required Nested object.

Nested fields

spend_controls.supports_max_cost

boolean required Whether callers can declare a maximum spend in this descriptor; the live manifest returns false.

spend_controls.supports_wallet_delegation

boolean required Whether wallet delegation is supported in this descriptor; the live manifest returns false.

spend_controls.supports_receipts

boolean required Whether paid calls support receipts; the live manifest returns true.

links

object required Nested object.

Nested fields

links.docs

string required Agent-readable docs index URL.

links.openapi

string required OpenAPI descriptor URL.

links.mcp

string required MCP descriptor URL.

links.x402

string required x402 payment descriptor URL.

links.pricing_strategy

string required Public payments and pricing-strategy documentation URL.

links.organization

string required Public organization/about page URL.

GET /prices

Alias of GET /.well-known/agent-pricing.json. Same handler, same JSON shape, and same Cache-Control: public, max-age=60; the canonical machine-readable URL remains /.well-known/agent-pricing.json.

Request example

curl "https://sigildex.ai/prices"

import requests

params = {}
response = requests.get("https://sigildex.ai/prices", params=params)
response.raise_for_status()
print(response.json())

const params = new URLSearchParams({});
const response = await fetch(`https://sigildex.ai/prices?${params}`);
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

Request parameters

No request parameters.

Response example

{
  "service": "sigildex",
  "pricing_strategy_version": "2026-05-06",
  "billing_modes": [
    "free",
    "x402_exact"
  ],
  "billing_modes_planned": [
    "x402_upto",
    "credits",
    "mpp_spt"
  ],
  "free_tier": {
    "anonymous": {
      "workflows_per_day": 50
    }
  },
  "prices": {
    "discover_workflow": {
      "unit": "workflow",
      "definition": "1 ranked skill search + shortlist review of up to 5 candidates within 1h TTL (1 discover + up to 5 inspect)",
      "usd": "0.002"
    }
  },
  "safety": {
    "inspect_discovered_results_is_free": true,
    "charge_failed_responses": false,
    "max_inspects_per_workflow": 5,
    "query_id_ttl_seconds": 3600
  },
  "spend_controls": {
    "supports_max_cost": false,
    "supports_wallet_delegation": false,
    "supports_receipts": true
  },
  "links": {
    "docs": "https://sigildex.ai/llms.txt",
    "openapi": "https://sigildex.ai/openapi.json",
    "mcp": "https://sigildex.ai/.well-known/mcp.json",
    "x402": "https://sigildex.ai/.well-known/x402.json",
    "pricing_strategy": "https://sigildex.ai/docs/payments",
    "organization": "https://sigildex.ai/about"
  }
}

Response fields

service

string, const "sigildex" required Service identifier; the live pricing manifest returns "sigildex".

pricing_strategy_version

string required Pricing-language version for this manifest; the live descriptor currently returns "2026-05-06".

billing_modes

array required Billing modes live today; the current manifest returns ["free", "x402_exact"].

Nested fields

billing_modes[]

string, enum "free" | "x402_exact" required Live billing mode. "free" is the free tier; "x402_exact" is exact per-workflow payment via x402.

billing_modes_planned

array required Billing modes planned but not live; the current manifest returns ["x402_upto", "credits", "mpp_spt"].

Nested fields

billing_modes_planned[]

string, enum "x402_upto" | "credits" | "mpp_spt" required Planned billing mode. "x402_upto", "credits", and "mpp_spt" are trajectory signals, not live payment rails.

free_tier

object required Nested object.

Nested fields

free_tier.anonymous

object required Nested object.

Nested fields

free_tier.anonymous.workflows_per_day

integer required Anonymous free-tier allowance; the live manifest returns 50 discovery workflows per day per IP.

prices

object required Billable products keyed by product id. "discover_workflow" is live today and always present; additional product keys may appear as new products ship.

Nested fields

prices.discover_workflow

object required The live billable product: one discovery workflow. Always present in the live manifest.

Nested fields

prices.discover_workflow.unit

string required Billable unit for this product; discover_workflow currently uses "workflow".

prices.discover_workflow.definition

string required Human-readable product definition; discover_workflow is "1 ranked skill search + shortlist review of up to 5 candidates within 1h TTL (1 discover + up to 5 inspect)".

prices.discover_workflow.usd

string required USD price string without a leading dollar sign; the default discover_workflow price is "0.002".

prices{}

object Billable product entry keyed by product id.

Nested fields

prices{}.unit

string required Billable unit for this product; discover_workflow currently uses "workflow".

prices{}.definition

string required Human-readable product definition; discover_workflow is "1 ranked skill search + shortlist review of up to 5 candidates within 1h TTL (1 discover + up to 5 inspect)".

prices{}.usd

string required USD price string without a leading dollar sign; the default discover_workflow price is "0.002".

safety

object required Nested object.

Nested fields

safety.inspect_discovered_results_is_free

boolean required Whether inspecting results from a discovery workflow is free when authorized by query_id; the live manifest returns true.

safety.charge_failed_responses

boolean required Whether failed application responses are charged; the live manifest returns false.

safety.max_inspects_per_workflow

integer required Maximum free inspect calls attached to one discovery workflow; the live manifest returns 5.

safety.query_id_ttl_seconds

integer required Lifetime of the query_id entitlement in seconds; the live manifest returns 3600.

spend_controls

object required Nested object.

Nested fields

spend_controls.supports_max_cost

boolean required Whether callers can declare a maximum spend in this descriptor; the live manifest returns false.

spend_controls.supports_wallet_delegation

boolean required Whether wallet delegation is supported in this descriptor; the live manifest returns false.

spend_controls.supports_receipts

boolean required Whether paid calls support receipts; the live manifest returns true.

links

object required Nested object.

Nested fields

links.docs

string required Agent-readable docs index URL.

links.openapi

string required OpenAPI descriptor URL.

links.mcp

string required MCP descriptor URL.

links.x402

string required x402 payment descriptor URL.

links.pricing_strategy

string required Public payments and pricing-strategy documentation URL.

links.organization

string required Public organization/about page URL.

MCP tools

Text fallbacks include Safety: <status> - <action hint>. Structured content mirrors the REST response plus MCP-only version. The Sigildex verdict line (Safety:) is emitted first, before author-provided name/description, and /inspect wraps author-provided SKILL.md content in an explicit untrusted fence.

Optional: send Authorization: SIWX <token> on the MCP HTTP request to use a wallet or allocation free-tier bucket. Missing SIWX auth stays anonymous.

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 Maximum number of results to return (default 10)

source

string, enum "main" | "github" 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 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 Human-browsable SKILL.md source URL to resolve before payment.

content_hash

string Stored sha256 content hash (sha256:<hex> accepted) to resolve before payment.

skill_id

string Skill UUID from discover_skills results (results[].skill_id).

query_id

string query_id from the discover_skills call that found this skill (1h TTL).

verify_skill

Mirrors GET /verify.

Input fields

content_hash

string Stored sha256 content hash (sha256:<hex> accepted). Provide content_hash, source_url, or both for a cross-check.

source_url

string Human-browsable SKILL.md source URL. Provide content_hash, source_url, or both for a cross-check.

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

No wallet is needed for anonymous free discovery, /verify, or the SIWX token exchange. Use SIGILDEX_WALLET_KEY only to enable x402 auto-pay beyond the free discovery tiers. 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. Invalid or expired SIWX auth returns INVALID_AUTH. Wallet, identity-store, search, or embedding dependency outages return DEPENDENCY_UNAVAILABLE. Free-tier exhaustion returns PAYMENT_REQUIRED with an x402 challenge; partner allocation exhaustion returns ALLOCATION_QUOTA_EXHAUSTED; authentication-attempt throttling and hard rate limits return 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.

Rate limits

Free tier: 50 discovery workflows per day per IP for anonymous callers, resets midnight UTC. Sign once with a wallet for a higher free tier, then send Authorization: SIWX <token> on /discover, /inspect, or the MCP HTTP request. /inspect is free with a valid query_id (up to 5 per id within the 1h TTL), and SIWX can use a wallet or allocation free-tier bucket before paid fallback. Beyond the free tiers, $0.002 per workflow via x402 — see Payments. X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset report the principal bucket used by the request: anonymous IP, SIWX wallet, or partner allocation.