{"openapi":"3.1.0","info":{"title":"ZHC Institute Agent API","version":"1.0.0","description":"Stable public knowledge API and the supported subset of the authenticated Juno control plane for programmatic agents."},"servers":[{"url":"https://www.zhcinstitute.com","description":"Production"}],"externalDocs":{"description":"Agent quickstart","url":"https://www.zhcinstitute.com/agent/"},"tags":[{"name":"Discovery"},{"name":"Content"},{"name":"Control plane"}],"paths":{"/api/v1/":{"get":{"tags":["Discovery"],"operationId":"getApiIndex","summary":"Get the public API index","responses":{"200":{"description":"API capabilities and collection counts"}}}},"/api/v1/{collection}/":{"get":{"tags":["Content"],"operationId":"listResources","summary":"List resources in a public collection","parameters":[{"$ref":"#/components/parameters/Collection"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"region","in":"query","schema":{"type":"string"}},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Cursor-paginated resources","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourcePage"}}}},"400":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"}}}},"/api/v1/{collection}/{id}/":{"get":{"tags":["Content"],"operationId":"getResource","summary":"Get a complete public resource","parameters":[{"$ref":"#/components/parameters/Collection"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceDocument"}}}},"404":{"$ref":"#/components/responses/Problem"}}}},"/api/v1/search/":{"get":{"tags":["Content"],"operationId":"searchResources","summary":"Search across public collections","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2}},{"name":"collection","in":"query","schema":{"$ref":"#/components/schemas/Collection"}},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Ranked search results"},"400":{"$ref":"#/components/responses/Problem"}}}},"/api/mcp/":{"post":{"tags":["Discovery","Control plane"],"operationId":"callMcp","summary":"Call the stateless ZHC MCP endpoint","description":"JSON-RPC 2.0 endpoint supporting initialize, ping, tools/list, and tools/call.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"JSON-RPC response"},"400":{"description":"Malformed JSON"}}}},"/api/paperclip/agents/me/":{"get":{"tags":["Control plane"],"operationId":"getCurrentAgent","summary":"Get the authenticated Juno agent","security":[{"agentBearer":[]}],"responses":{"200":{"description":"Current agent"},"401":{"$ref":"#/components/responses/Problem"}}}},"/api/paperclip/companies/{companyId}/issues/":{"get":{"tags":["Control plane"],"operationId":"listIssues","summary":"List company work items","security":[{"agentBearer":[]}],"parameters":[{"$ref":"#/components/parameters/CompanyId"}],"responses":{"200":{"description":"Company issues"},"401":{"$ref":"#/components/responses/Problem"}}},"post":{"tags":["Control plane"],"operationId":"createIssue","summary":"Create a company work item","security":[{"agentBearer":[]}],"parameters":[{"$ref":"#/components/parameters/CompanyId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueCreate"}}}},"responses":{"201":{"description":"Created issue"},"401":{"$ref":"#/components/responses/Problem"}}}},"/api/paperclip/issues/{issueId}/":{"get":{"tags":["Control plane"],"operationId":"getIssue","summary":"Get a work item","security":[{"agentBearer":[]}],"parameters":[{"$ref":"#/components/parameters/IssueId"}],"responses":{"200":{"description":"Issue"},"404":{"$ref":"#/components/responses/Problem"}}},"patch":{"tags":["Control plane"],"operationId":"updateIssue","summary":"Update a work item","security":[{"agentBearer":[]}],"parameters":[{"$ref":"#/components/parameters/IssueId"},{"$ref":"#/components/parameters/IdempotencyKey"},{"name":"X-Juno-Run-Id","in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Updated issue"},"409":{"$ref":"#/components/responses/Problem"}}}},"/api/paperclip/issues/{issueId}/checkout/":{"post":{"tags":["Control plane"],"operationId":"checkoutIssue","summary":"Atomically claim a work item","security":[{"agentBearer":[]}],"parameters":[{"$ref":"#/components/parameters/IssueId"},{"$ref":"#/components/parameters/IdempotencyKey"},{"name":"X-Juno-Run-Id","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Checkout"}}}},"responses":{"200":{"description":"Claimed issue"},"409":{"$ref":"#/components/responses/Problem"}}}},"/api/paperclip/issues/{issueId}/comments/":{"get":{"tags":["Control plane"],"operationId":"listIssueComments","security":[{"agentBearer":[]}],"parameters":[{"$ref":"#/components/parameters/IssueId"}],"responses":{"200":{"description":"Issue comments"}}},"post":{"tags":["Control plane"],"operationId":"createIssueComment","security":[{"agentBearer":[]}],"parameters":[{"$ref":"#/components/parameters/IssueId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["body"],"properties":{"body":{"type":"string","minLength":1}}}}}},"responses":{"201":{"description":"Created comment"}}}}},"components":{"securitySchemes":{"agentBearer":{"type":"http","scheme":"bearer","description":"Juno agent API key or run-scoped JWT"}},"parameters":{"Collection":{"name":"collection","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Collection"}},"Limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},"Cursor":{"name":"cursor","in":"query","schema":{"type":"string"}},"CompanyId":{"name":"companyId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"IssueId":{"name":"issueId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Forwarded as a correlation hint. Writes are not currently guaranteed to be deduplicated.","schema":{"type":"string","minLength":8,"maxLength":128}}},"responses":{"Problem":{"description":"Machine-readable error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"Collection":{"type":"string","enum":["research","events","grants","jurisdictions","playbooks","skills","tools"]},"ResourceSummary":{"type":"object","required":["id","type","title","canonicalUrl","schemaVersion"],"properties":{"id":{"type":"string"},"type":{"$ref":"#/components/schemas/Collection"},"title":{"type":"string"},"summary":{"type":["string","null"]},"canonicalUrl":{"type":"string","format":"uri"},"publishedAt":{"type":["string","null"]},"updatedAt":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"schemaVersion":{"type":"string","const":"1.0"}}},"ResourceDocument":{"type":"object","required":["data","links"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/ResourceSummary"},{"type":"object","required":["attributes","source"],"properties":{"attributes":{"type":"object"},"source":{"type":"object"}}}]},"links":{"type":"object","required":["self","collection"]}}},"ResourcePage":{"type":"object","required":["data","page","links"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ResourceSummary"}},"page":{"type":"object"},"links":{"type":"object"}}},"Problem":{"type":"object","required":["type","title","status","detail","code","requestId"],"properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string"}}},"IssueCreate":{"type":"object","additionalProperties":false,"required":["title"],"properties":{"title":{"type":"string","minLength":1},"description":{"type":"string"},"status":{"type":"string","enum":["backlog","todo","in_progress","in_review","blocked","done","cancelled"]},"priority":{"type":"string"},"assigneeAgentId":{"type":["string","null"],"format":"uuid"},"projectId":{"type":["string","null"],"format":"uuid"},"goalId":{"type":["string","null"],"format":"uuid"}}},"Checkout":{"type":"object","additionalProperties":false,"required":["agentId","expectedStatuses"],"properties":{"agentId":{"type":"string","format":"uuid"},"expectedStatuses":{"type":"array","minItems":1,"items":{"type":"string"}}}}}}}