{"openapi":"3.1.0","info":{"title":"Knotbind API","version":"1.0.0","description":"Check whether software is ready for AI agents, connect an MCP server, and keep it working. The same operations are available as MCP tools at /mcp. Approving production changes is human-only, in the dashboard."},"servers":[{"url":"https://www.knotbind.com"}],"security":[{"apiKey":[]},{"oauth2":["read","write"]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"kbk_…","description":"API key from POST /api/v1/signup or the dashboard. Scopes: read, write. The Owner can also create tool:execute and tool:execute:write keys in the dashboard for scoped execution grants."},"oauth2":{"type":"oauth2","description":"OAuth 2.1 authorization code with PKCE (S256). Dynamic client registration at /oauth/register. Metadata at /.well-known/oauth-authorization-server.","flows":{"authorizationCode":{"authorizationUrl":"https://www.knotbind.com/oauth/authorize","tokenUrl":"https://www.knotbind.com/oauth/token","refreshUrl":"https://www.knotbind.com/oauth/token","scopes":{"read":"Status, Runs, Findings, tools, assistant connections","write":"Run Checks, change Checks, connect MCP servers, relay URLs"}}}}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":[]}},"required":[]}}}}}},"paths":{"/api/v1/signup":{"post":{"summary":"Create a workspace and get an API key (shown once)","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"}},"required":["company","name","email"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/readiness":{"post":{"summary":"Run an Agent Readiness Check on a website","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/readiness/{id}":{"get":{"summary":"Get a stored readiness report","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/integration":{"post":{"summary":"Connect an MCP server, add read-only Checks, run the Baseline","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mcp_url":{"type":"string"}},"required":["mcp_url"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/status":{"get":{"summary":"Health, Finding, Checks and the last Run","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/runs":{"get":{"summary":"Recent Runs","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Run Checks now","responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/finding":{"get":{"summary":"Open Finding, diagnosis and Repair Proposal","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/tools":{"get":{"summary":"Live tools/list from the connected MCP server","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/checks":{"post":{"summary":"Add an MCP tool as a Check","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string"},"arguments":{"type":"object"},"allow_write":{"type":"boolean"}},"required":["tool"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/tools/call":{"post":{"summary":"Call one MCP tool once; write tools require explicit allow_write consent and are not scheduled","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string","minLength":1,"maxLength":100},"arguments":{"type":"object"},"allow_write":{"type":"boolean"},"accept_definition_change":{"type":"boolean"}},"required":["tool"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/checks/{id}":{"delete":{"summary":"Remove a Check","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/assistants":{"get":{"summary":"Which AI assistants are connected, and how that is known","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/relay":{"post":{"summary":"Create a relay URL that detects real assistants","responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/plan":{"get":{"summary":"Plan (Free, Pro, Business), billing status, limits and usage","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/billing/checkout":{"post":{"summary":"Create a Stripe Checkout link for Pro or Business; a person opens it and pays","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string","enum":["pro","business"]}},"required":["plan"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/billing/plan-request":{"post":{"summary":"Ask the Owner to approve a plan change; does not change billing","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string","enum":["pro","business"]},"reason":{"type":"string","maxLength":500}},"required":["plan"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/keys":{"get":{"summary":"List API keys","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Create an API key (shown once)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"scopes":{"type":"array","items":{"enum":["read","write"]}}},"required":[]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/credential-grants/{id}/token":{"post":{"summary":"Rotate a temporary execution token for an Owner-approved grant","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"description":"Requires the exact API key approved by the Owner with tool:execute scope and Build entitlement. Returns a scoped relay URL, expiry and allowed tool names, never an upstream credential. The same API key must authenticate relay calls. Rotation revokes the old token and cannot extend expiry or widen permissions. Owner creates/revokes grants in the Build dashboard; interactive OAuth delegation is not supported.","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/vault/grants/{id}/token":{"post":{"summary":"Rotate an Owner-approved vault operation token","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"description":"API key or OAuth client/member identity with tool:execute and Business access required. Rotation preserves the Owner deadline, credential version and exact operations. No upstream credential is returned.","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/vault/grants/{id}/execute":{"post":{"summary":"Execute an exact Owner-approved credential operation","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"description":"Requires the identity Bearer credential and X-Knotbind-Execution-Token. Body contains operation and object arguments. No arbitrary URL, retry or raw credential vending. Gateway alias: /v1/credential-grants/{id}/execute.","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Knotbind-Execution-Token","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["operation","arguments"],"properties":{"operation":{"type":"string"},"arguments":{"type":"object"}}}}}}}},"/api/v1/keys/{id}":{"delete":{"summary":"Revoke an API key","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}}}}