klisten.API quickstartAccount

BUILD WITH EVIDENCE

Start with one approved integration.

ToolGuard checks execution policy. ToolRank helps you inspect a tool catalog. Availability and access depend on the features enabled for your deployment.

1. Arrange access

Sign in on the account page and create an API key with the permissions enabled for your account. For ToolGuard onboarding, email [email protected] with your integration and intended tools to obtain an approved service ID, tool name, fingerprint, policy version, organization ID, and policy hash.

Online self-service payments are not available. Access or an API key does not imply that every service is live. Check the deployment's OpenAPI contract for enabled routes.

Examples below contain placeholders only. Replace every REPLACE value with your approved configuration. Keep API keys on your server or in a secret manager, never in public browser code. The base URL is https://api.klisten.co.kr.

2. Check a ToolGuard policy

POST /v1/gate/check requires gate:check. This checks an operator-onboarded service against existing evidence and policy; it does not perform a new scan or guarantee complete security.

curl --fail-with-body 'https://api.klisten.co.kr/v1/gate/check' \
  -H 'Authorization: Bearer REPLACE_WITH_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: REPLACE_WITH_UNIQUE_REQUEST_ID' \
  --data '{
    "service_id": "svc_REPLACE_WITH_APPROVED_UUID",
    "tool_name": "REPLACE_WITH_APPROVED_TOOL_NAME",
    "expected_fingerprint": "sha256:REPLACE_WITH_64_LOWERCASE_HEX_CHARACTERS",
    "policy_version": "REPLACE_WITH_APPROVED_POLICY_VERSION"
  }'

The optional agent_id has the form agt_<UUID>. An idempotency key must contain 16–128 letters, numbers, dots, underscores, colons, or hyphens. Reuse the same key and identical body when recovering the same request; use a new key for a new decision.

Read decision (allow, deny, review, or unknown), reasons, expires_at, and next_action. A successful HTTP response is not execution permission. Do not execute on a non-allow, expired, or invalid receipt.

Verify immediately before execution

The repository-local TypeScript and Python SDKs expose ChristineClient.check() for inspection and ChristineClient.execute(binding, callback) for guarded execution. TypeScript also provides assertAllowed(); Python uses assert_allowed(). Configure the trusted issuer, organization ID, API key, and policy hash through administration. The execution wrapper verifies the signed receipt, binding, expiry, and current online attestation status before invoking your callback; it needs attestations:read as well as gate:check.

These SDKs are repository-local sources, not published package-registry releases. Ask for integration access. scan() and poll() collect and read evidence; a successful scan alone does not authorize execution.

3. Discover tools with ToolRank

Catalog beta · GET /v1/toolrank/tools requires tools:read. Optional query fields are search, capability, transport, cursor, and limit (1–100; default 20).

curl --fail-with-body \
  'https://api.klisten.co.kr/v1/toolrank/tools?limit=20&transport=streamable_http' \
  -H 'Authorization: Bearer REPLACE_WITH_API_KEY'

Use next_cursor for pagination. Get one entry at GET /v1/toolrank/tools/{id}. Catalog coverage is partial_or_unverified; publisher registration is not safety approval, and missing measurements are not zero latency or perfect availability.

Request an evidence-based selection

POST /v1/toolrank/select requires tools:select and an idempotency key. Send the request object directly:

curl --fail-with-body 'https://api.klisten.co.kr/v1/toolrank/select' \
  -H 'Authorization: Bearer REPLACE_WITH_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: REPLACE_WITH_UNIQUE_REQUEST_ID' \
  --data '{
    "capabilities": ["REPLACE_WITH_CATALOG_CAPABILITY"],
    "transport": "streamable_http",
    "location": "REPLACE_WITH_MEASUREMENT_LOCATION",
    "max_age_seconds": 3600,
    "min_samples": 5,
    "min_availability_bps": 9900,
    "require_policy_approval": true
  }'

Transport may be streamable_http, stdio, or sse. Availability uses basis points: 9900 means 99%. Optional constraints are max_latency_ms and max_cost_micro_usd. A catalog without sufficient independent observations or policy evidence can correctly return NO_ELIGIBLE_TOOL and a null selected_id. Inspect ranked, excluded, and their reasons; a selection does not execute a tool or grant permission.

Retrieve the saved decision using GET /v1/toolrank/decisions/{id}, where id is the returned decision UUID, with tools:read. ToolRank uses the HTTP endpoints above; the current SDK does not expose ToolRank convenience methods.

ModelRoute discovery beta

Public endpoint: GET https://api.klisten.co.kr/v1/modelroute/catalog. This is metadata-only discovery, not a model execution service or a quality leaderboard. No API key is required. Read the discovery OpenAPI contract or browse the catalog.

Check expires_at before using returned metadata. Catalog inclusion, provider descriptions, and advertised free access do not guarantee current availability, account eligibility, model quality, or zero total cost. Discovery metadata must not be treated as a tested quality score.

Handle failures conservatively

Keep the response request ID for support. Authentication and permission failures need corrected credentials or scopes; an unavailable feature needs operator confirmation. For ambiguous POST outcomes, preserve the original idempotency key. Never treat an error, missing evidence, or unavailable verification service as approval.

Ask about onboarding or integration support · Open account

MeterMCP: read your key's usage

Create an API key in Account with meter:read. This read-only beta reports this key's real Klisten reservation ledger, with exact integer micro-USD strings (1 USD = 1,000,000 micro-USD). It does not report external provider settlement.

curl --fail-with-body 'https://api.klisten.co.kr/v1/metermcp/usage?from=2026-10-01&to=2026-10-08' \
  -H 'Authorization: Bearer REPLACE_WITH_API_KEY'

Use an inclusive UTC range of at most 31 days. The result is the current reservation state grouped by budget day, not an immutable historical balance or refund statement. Keys cannot read another key's usage. Empty periods return zero.

AgentEscrow: unfunded task drafts

When /v1/agentescrow/drafts appears in the deployment contract, create a key with escrow:write and escrow:read. Submit an EscrowDraftRequest from that contract as draft.json; use real repository/commit/patch/profile/image identifiers and a future UTC deadline. Party identifiers express proposed terms, not proof of either party's consent.

curl --fail-with-body 'https://api.klisten.co.kr/v1/agentescrow/drafts' \
  -H 'Authorization: Bearer REPLACE_WITH_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: REPLACE_WITH_UNIQUE_REQUEST_ID' \
  --data-binary @draft.json
curl --fail-with-body 'https://api.klisten.co.kr/v1/agentescrow/drafts/REPLACE_WITH_DRAFT_UUID' \
  -H 'Authorization: Bearer REPLACE_WITH_API_KEY'

All drafts are private to your organization and remain UNFUNDED_DRAFT. No funding, payment, escrow custody, payout or release occurs. Receipt verification stays unavailable unless separately configured. Limits: 100 retained drafts and 30 requests per organization per minute. Reuse the same idempotency key and body for retries; changed content conflicts.

AgentScore: private credential activity beta

After registering credential activity in your account, verified members can use agents:write with POST /v1/agentscore/activity and a body containing only scan_job_id, then agents:read with GET /v1/agentscore/activity/{jobId}. The eligible paid ToolGuard scan must belong to the same authenticated organization and API key. Do not submit an organization or key override.

These are private, first-party factual records, not reputation scores, independent assessments, or guarantees of task success. Each organization must complete registration before issuance is available; see customer access. Missing evidence is not fabricated: an unavailable issuer or ineligible source is rejected. Successful issuance against an eligible production observation has not yet been demonstrated.

ClearGate: free documentation grants

This beta checks a signed grant for Klisten-authored text and Klisten-owned examples at the exact resource https://klisten.co.kr/docs.html. Read the documentation agent license. Verified members can request their own free grant in the account after accepting the published conditions. Creating an API key alone does not issue a grant.

Use a key with content:check and the actual grant ID returned by your account:

curl --fail-with-body https://api.klisten.co.kr/v1/cleargate/check \
  -H 'Authorization: Bearer REPLACE_WITH_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"grant_id":"REPLACE_WITH_CURRENT_GRANT_ID","intent":{"publisher_id":"klisten-inc","resource":"https://klisten.co.kr/docs.html","audience":"klisten-cleargate-docs-v1","purpose":"api-docs-read","territory":"KR","redistribute":false}}'

Permitted purposes are api-docs-read and api-docs-summarize for internal API use worldwide in the selected supported territory. Each free grant lasts at most 30 minutes and is revocable. Renewal is not automatic. An expired or revoked grant, wrong scope, missing evidence, or unavailable registry is not permission. Check before each new use; do not keep using an old AUTHORIZED response.

This service checks permission evidence; it does not certify ownership, fetch content, collect a content payment, grant third-party rights, or authorize model training or external redistribution. Request a current grant in your account; see the customer access guide.