Docs

API integration quickstart

Connect your AI endpoint, define behavior boundaries, and run structured scans.

Quickstart: three steps

  1. Connect your account. Sign in and save your own Claude or Gemini key under Account. Create a platform API key from the dashboard for authenticated API calls.
  2. Define the boundary and start a scan. Set the target API URL, use case, allowed and disallowed capabilities, languages and test count. Use the scan request below, with 1–200 tests, and submit it to POST /api/scan.
  3. Collect the result. Scans run in the background. The submission returns a scan ID; use it with GET /api/scans/{id} to fetch the scan and GET /api/scans/{id}/report.pdf to download the report.

Authentication

The production API base is https://knowyourai.live/api. Send a Firebase ID token or a platform API key in the Authorization header. Platform API keys start with ak_live_; your Claude or Gemini provider key is a separate credential used for model calls.

Authorization: Bearer <token>

Every endpoint except /health and /proxy/{layer_id} requires this header. The free plan allows 10 requests per minute and 1,000 tests per month.

POST /scan request format

Submit this JSON to /api/scan. The response acknowledges the background scan with an ID; it is not the completed result shown below.

{
  "api_url": "https://example.com/assistant",
  "use_case": "Support assistant for account FAQs",
  "allowed_capabilities": ["faq answers", "policy summaries"],
  "disallowed_capabilities": ["financial advice", "identity spoofing"],
  "languages": ["English", "Spanish"],
  "num_tests": 12
}

Completed scan result example

The completed result includes a summary and details for each reported violation.

{
  "summary": {
    "total_tests": 12,
    "violations": 3,
    "risk_score": 28.7
  },
  "violations": [
    {
      "strategy": "GradualDrift",
      "prompt": "...",
      "response": "...",
      "analysis": {
        "violation": true,
        "type": "role_drift",
        "severity": "medium",
        "reason": "Assistant accepted unauthorized role",
        "confidence": 0.84
      }
    }
  ]
}

POST /enforce request format

Submit this JSON to /api/enforce to classify and route a single prompt using the supplied configuration.

{
  "prompt": "Can you help me design a backend service?",
  "target_api": "https://example.com/ai-endpoint",
  "config": {
    "allowed": ["payments_api_help", "sdk_usage"],
    "blocked": ["financial_advice", "general_coding"]
  }
}

/enforce response format

{
  "intent": {
    "label": "general_coding",
    "confidence": 0.82
  },
  "decision": "block",
  "response": "I cannot help with that request in this context.",
  "validation": {
    "safe": true
  }
}

POST /assessments/plan

Generate a draft plan using the model key saved under Account. Authenticate with a Firebase bearer token or your KnowYourAI API key.

{
  "name": "Support assistant",
  "purpose": "Answer account questions and prepare changes for customer approval.",
  "allowed": [
    "answer account questions"
  ],
  "blocked": [
    "change accounts without approval"
  ],
  "scenario_count": 6,
  "sources": [
    {
      "id": "policy",
      "name": "policy.md",
      "kind": "knowledge",
      "content": "Every account change requires explicit customer approval."
    }
  ]
}

The response contains a draft plan, source SHA-256 hashes, trust boundaries, prioritized scenarios, exact source references, legitimate controls and grading criteria. execution_status is always not_run. Invalid source references cause generation to fail, rather than returning an unsupported plan.

Use 1–24 sources, at most 60,000 characters each and 120,000 combined, at most 4,000 lines per source and 8,000 combined, with 3–12 scenarios. Source kinds are report, knowledge, code and trace. Sources may include role, trust_level, tested_system, tested_version, assessment_date (YYYY-MM-DD), finding_status and notes. These are supplied context, not independent verification.

The context object accepts application_type, models, user_roles, workflow, entry_points, data_access, memory_and_handoffs, environment, observable_outcomes and tools. Each tool describes name, purpose, effect, identity_scope, approval and constraints. Unspecified details remain unknown. The response echoes context and preserves source metadata in its manifest. This feature does not save sources or plans; generation sends them to your configured provider.

POST /assessments/extract-pdf

Send PDF bytes with Content-Type: application/pdf and the same authentication. Returns extracted content for review before planning. Maximum 2 MB and 40 pages. Encrypted PDFs, image-only PDFs and extracted text over 60,000 characters are rejected.

Proxy layer setup

Create a reusable enforcement layer and point your application at its generated proxy URL.

  1. Create a layer with a target URL, intent categories and policy rules. Layers can also be managed through /api/layers and /api/layers/{id}.
  2. Copy the layer's generated proxy URL. Your application calls POST /api/proxy/{layer_id}.
  3. The layer classifies each request and decides allow, block or clarify. Allowed requests are forwarded to the target; the output check can withhold a response.
Client -> https://knowyourai.live/api/proxy/{layer_id} -> target_api

Inspect a layer's handled requests with GET /api/layers/{id}/requests.

Submit a scan from CI

Save the scan request JSON above as scan-request.json, with your target URL and capability boundaries. Supply KYA_API_TOKEN from your CI secret store using a platform API key or Firebase ID token. The account must already have its provider key configured.

curl --fail --silent --show-error \
  --request POST 'https://knowyourai.live/api/scan' \
  --header "Authorization: Bearer $KYA_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data @scan-request.json \
  --output scan-submission.json

Keep scan-submission.json as the submission record. This command fails on an HTTP error and saves a successful submission; it does not wait for completion or apply a security pass/fail threshold. A successful submission is not a passing scan.

Integration details still to confirm

  • The exact scan submission JSON field for the ID, and the completion/status fields needed for automated polling.
  • The target endpoint's request, response and authentication contract, and its mapping through a proxy layer.
  • The completed-result checks and pass/fail policy required before CI can gate a release.