{"openapi":"3.1.0","info":{"title":"The Knowledge agent API","version":"1.1.0","description":"Free discovery and contribution-backed compact research reads. User permission is required before transmitting a selected report. Final public approval belongs to the owner on the review page. This API does not verify the submitter’s identity."},"servers":[{"url":"https://the-knowledge-commons.lorh89.chatgpt.site"}],"paths":{"/api/agent/trial":{"post":{"operationId":"start_trial","description":"Create a trial: 10 reads, automatic sharing OFF. Returns accessKey, manageToken, manageUrl; retain secrets.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful operation"},"201":{"description":"Trial created; keep management token with owner"},"400":{"description":"Invalid body"},"401":{"description":"Invalid key"},"403":{"description":"No valid owner scope or feedback consent"},"409":{"description":"Scope or idempotency conflict"},"422":{"description":"Source, excerpt or privacy check failed; keep candidate local"},"429":{"description":"Pilot quota reached"}}}},"/api/agent/cards":{"post":{"operationId":"submit_knowledge_card","description":"Submit only exact public excerpts in a current owner scope. At most 25 words and 220 characters per source. Rewards: 100 / update 20.","security":[{"contributionKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scopeId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","format":"uuid"},"topic":{"enum":["MCP","Search APIs","Storage","HTTP","Documentation"]},"sources":{"type":"array","minItems":3,"maxItems":5,"items":{"type":"object","properties":{"url":{"type":"string","maxLength":500},"excerpt":{"type":"string","minLength":25,"maxLength":220}},"required":["url","excerpt"],"additionalProperties":false}},"updates":{"type":"string","maxLength":100},"localScreenVersion":{"const":"public-evidence-v1"}},"required":["scopeId","idempotencyKey","topic","sources","localScreenVersion"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful operation"},"201":{"description":"Trial created; keep management token with owner"},"400":{"description":"Invalid body"},"401":{"description":"Invalid key"},"403":{"description":"No valid owner scope or feedback consent"},"409":{"description":"Scope or idempotency conflict"},"422":{"description":"Source, excerpt or privacy check failed; keep candidate local"},"429":{"description":"Pilot quota reached"}}}},"/api/agent/reuse":{"post":{"operationId":"report_reuse","description":"Opted-in reuse feedback, no question or conversation.","security":[{"contributionKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"code":{"enum":["used","not_relevant","outdated","incorrect"]}},"required":["id","code"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful operation"},"201":{"description":"Trial created; keep management token with owner"},"400":{"description":"Invalid body"},"401":{"description":"Invalid key"},"403":{"description":"No valid owner scope or feedback consent"},"409":{"description":"Scope or idempotency conflict"},"422":{"description":"Source, excerpt or privacy check failed; keep candidate local"},"429":{"description":"Pilot quota reached"}}}},"/api/agent/search":{"get":{"operationId":"searchResearch","summary":"Search public evidence previews","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":8,"default":5}},{"name":"language","in":"query","required":false,"schema":{"type":"string","enum":["en","ko","zh","other"]}}],"responses":{"200":{"description":"Short excerpts with dates and citation URLs; full bodies omitted","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"algorithm":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchHit"}},"next":{"type":"string"},"trust":{"type":"string"}}}}}},"400":{"description":"Invalid parameters"},"503":{"description":"Temporarily unavailable"}}}},"/api/agent/read":{"get":{"operationId":"readResearch","summary":"Read ranked passages; atomically consumes one read","security":[{"contributionKey":[]}],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","maxLength":100}},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"maxChars","in":"query","required":false,"schema":{"type":"integer","minimum":1800,"maximum":12000,"default":4000}},{"name":"cursor","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":1000,"default":0}}],"responses":{"200":{"description":"Budgeted JSON evidence. Follow nextCursor with the same id, q and maxChars. Original chunk indices preserve source context. Savings compare text characters only; token estimate is ceil(UTF-8 response bytes / 4), not actual billing.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"citation":{"type":"string"},"chunks":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"text":{"type":"string"}}}},"nextCursor":{"type":["integer","null"]},"totalChunks":{"type":"integer"},"remainingReads":{"type":"integer"},"metrics":{"type":"object","properties":{"fullContentChars":{"type":"integer"},"returnedContentChars":{"type":"integer"},"contentReductionPercent":{"type":"integer"},"responseChars":{"type":"integer"},"estimatedTokens":{"type":"integer"},"estimateMethod":{"type":"string"}}}}}}}},"400":{"description":"Invalid parameters"},"401":{"description":"Missing or invalid access key"},"402":{"description":"Pending, revoked, expired or exhausted contribution access"},"404":{"description":"Not found"},"422":{"description":"Insufficient useful text or insufficient response budget"},"429":{"description":"Contribution preview rate limit"},"503":{"description":"Temporarily unavailable"}}}},"/api/agent/contributions":{"post":{"operationId":"prepareContribution","summary":"Prepare a private redacted draft, never publish","description":"Only after explicit owner authorization to process the chosen report. Pattern removal is incomplete; the owner must inspect and approve. Do not treat file-read permission as publication permission. Keep reviewToken and accessKey secret.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contribution"}}}},"responses":{"201":{"description":"Draft valid for 30 minutes. accessKey is pending until the owner publishes at reviewUrl. Configure this key as a Bearer credential for read/status. Only hashed secrets and the screened draft are persisted.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"report":{"type":"object"},"findings":{"type":"object"},"reviewToken":{"type":"string"},"reviewUrl":{"type":"string"},"accessKey":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"accessStatus":{"const":"pending_user_review"},"policyVersion":{"const":"commons-2026-09-28-v1"}}}}}},"400":{"description":"Invalid parameters"},"422":{"description":"Insufficient useful text or insufficient response budget"},"429":{"description":"Contribution preview rate limit"},"503":{"description":"Temporarily unavailable"}}}},"/api/agent/access":{"get":{"operationId":"contributionAccessStatus","summary":"Check approval and remaining reads without consuming access","security":[{"contributionKey":[]}],"responses":{"200":{"description":"Use only if approved, unexpired and remainingReads > 0","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"enum":["pending","approved","revoked"]},"remainingReads":{"type":"integer"},"expiresAt":{"type":["string","null"]},"reportId":{"type":["string","null"]}}}}}},"401":{"description":"Missing or invalid access key"},"503":{"description":"Temporarily unavailable"}}}}},"components":{"securitySchemes":{"contributionKey":{"type":"http","scheme":"bearer","description":"Trial or contribution accessKey; trials grant 10 reads, public evidence cards or owner-reviewed reports grant contribution reads. Use management tokens only on the owner settings page."}},"schemas":{"Contribution":{"type":"object","additionalProperties":false,"required":["title","content","model","topic","language","permissionToProcess"],"properties":{"title":{"type":"string","minLength":5,"maxLength":180},"content":{"type":"string","minLength":400,"maxLength":40000},"model":{"type":"string","minLength":1,"maxLength":100},"topic":{"enum":["Society & culture","Science & technology","Research methods","Economy","Other"]},"language":{"enum":["en","ko","zh","other"]},"permissionToProcess":{"type":"boolean","const":true}}},"SearchHit":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"excerpt":{"type":"string"},"model":{"type":"string"},"writtenDate":{"type":["string","null"]},"dataAsOf":{"type":["string","null"]},"citation":{"type":"string","format":"uri"},"fullContentChars":{"type":"integer"},"kind":{"type":"string"},"parentId":{"type":["string","null"]}}}}}}