{"endpoint":"POST /api/v1/clearance","description":"Real-time security clearance for the AI agent skill you name, with an optional check that a ClawSecure content hash you hold (for example the audited version's hash you recorded at install) is still the hash ClawSecure holds for that skill.","request_fields":{"skill_identifier":"REQUIRED. The identifier of the skill being checked, formed from its source: github:owner/repo for a GitHub repository, github:owner/repo/path for a skill in a subfolder of one (the branch is not part of it), clawhub:owner/name for a ClawHub skill, or url:<source URL> for any other source. It must match ClawSecure's record exactly, letter case included; an identifier that matches no record answers UNKNOWN, never SECURE. The skill record, and so the audit you get, is resolved from this field alone; a submitted hash can only confirm that record or turn the answer into UNVERIFIED.","current_skill_hash":"Optional. A ClawSecure content hash for the named skill: 64 hex characters, either letter case, with or without a leading sha256: prefix. ClawSecure computes it over the skill's files; it is not a plain SHA-256 of the files or of an archive, so do not compute it yourself. Use the value ClawSecure publishes as contentHash for the audited version: in the skill's Security Audit Report data at GET /api/report/<scan id> (the scan id is the last segment of report_url) or in its entry in GET /api/registry. It is compared with the hash ClawSecure holds for the named skill and never selects a different skill. Once ClawSecure detects that the skill's source has changed since its audit, the audited version's hash answers UNVERIFIED, and a request without a hash answers PENDING_RESCAN while the change awaits re-audit.","agent_id":"Optional. Your own label for the calling agent. Echoed back, trimmed, on every 200 response and never used to decide the verdict.","action_context":"Optional. What the agent is about to do. Logged only."},"limits":{"unit":"JavaScript string length of the value as sent in UTF-16 code units, so some characters, such as many emoji, count more than 1","skill_identifier":512,"current_skill_hash":128,"agent_id":256,"action_context":256},"example_request":{"skill_identifier":"github:example-org/example-skill","current_skill_hash":"sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","agent_id":"my-agent-01"},"statuses":{"SECURE":"The named skill is audited, its security score is 80 or above, and any submitted hash matches the hash ClawSecure holds for it.","CAUTION":"The named skill is audited with a security score of 50 to 79. Review its Security Audit Report before granting sensitive access.","DENIED":"The named skill is audited with a security score below 50, or has no score. Restrict access.","UNVERIFIED":"The submitted hash differs from the hash ClawSecure holds for the named skill. The security score shown is the audited version's and says nothing about the content your hash describes.","PENDING_RESCAN":"ClawSecure has recorded a change at the named skill's source that it has not yet cleared, so the audit on record may not describe the code there now. Check again later.","UNKNOWN":"No skill record matches this identifier exactly (letter case included): the skill has not been audited by ClawSecure, or it was audited under a different identifier. UNKNOWN is never a clearance."},"integrity_statuses":{"MATCH":"A hash was submitted and it equals the hash ClawSecure holds for the named skill.","MISMATCH":"A hash was submitted and it differs from the hash ClawSecure holds for the named skill.","NOT_CHECKED":"No hash was submitted; the verdict rests on the audit alone.","STALE":"ClawSecure has recorded a change at the skill's source that it has not yet cleared (status PENDING_RESCAN). Any hash you sent matched that latest record.","NOT_FOUND":"No skill record matches the identifier exactly."},"echo":"Every 200 response repeats skill_identifier, and agent_id when you sent one, as the API read them: trimmed of leading and trailing whitespace. Compare them with the trimmed values you sent. No 400, 413, 429 or 500 response echoes anything.","errors":"400 with a JSON body {error, documentation} when skill_identifier is missing or a field is malformed; the error names the field. A body the JSON parser rejects (malformed JSON, or JSON that is not an object or array) gets a 400 that is not JSON, and a body over 100 kB a 413 that is not JSON. 429 when a rate limit is exceeded: usually a short text message, not JSON (the site-wide limit); the per-minute clearance limit answers a small JSON body {error}. 500 with a JSON body {error, documentation} on a server error. Check the HTTP status before you parse the body.","rate_limit":"100 requests per 15 minutes per client IP address (an IPv6 client is counted by its /56 network), shared with every other request that client makes to www.clawsecure.ai: pages, assets and API calls alike; this endpoint also allows at most 100 clearance calls per one-minute window per client (each window starts at the first call from that client after the previous window ends)","documentation":"https://github.com/ClawSecure/clawsecure-openclaw-security/blob/main/docs/API.md"}