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

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

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

## POST /inspect

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

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

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

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

`pin` is lockfile-ready: `{skill_id, source_url, content_hash, commit_sha, verdict, audited_at}`. Store it with the installed skill and re-check it through `/verify`. The `source.content_hash` and `safety.audited_content_hash` fields follow the [Verification](https://sigildex.ai/docs/identity) hash recipe and pin/verify contract.

## GET /verify

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

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

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

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

## GET /health

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

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

## MCP Tools

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

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

## CLI

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

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

## Errors

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

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