{"openapi":"3.0.3","info":{"title":"Aemulus Protocol API","version":"1.0.0","description":"Run browser-automation skills, read their extracted output, and verify their on-chain receipts. Authenticate with an API key (Bearer); receipt verification is public."},"servers":[{"url":"https://aemulusai.com"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","description":"An Aemulus API key, e.g. `aem_live_…`."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"RunRequest":{"type":"object","properties":{"skillId":{"type":"string","example":"skl_8c…"},"input":{"type":"object","additionalProperties":{"type":"string"},"description":"Field key → value for the skill's inputs."}},"required":["skillId"]},"Run":{"type":"object","properties":{"id":{"type":"string"},"skillId":{"type":"string"},"status":{"type":"string","enum":["running","awaiting_input","completed","needs_review","failed"]},"result":{"type":"string","nullable":true},"output":{"type":"object","nullable":true,"additionalProperties":{"type":"string"}},"receiptHash":{"type":"string","nullable":true},"steps":{"type":"integer"},"createdAt":{"type":"integer"}}},"RunListItem":{"type":"object","description":"List items omit `result` and `steps` (fetch a single run for those).","properties":{"id":{"type":"string"},"skillId":{"type":"string"},"status":{"type":"string","enum":["running","awaiting_input","completed","needs_review","failed"]},"output":{"type":"object","nullable":true,"additionalProperties":{"type":"string"}},"receiptHash":{"type":"string","nullable":true},"createdAt":{"type":"integer"}}},"RunStarted":{"type":"object","description":"POST /runs returns only these two fields (the run starts async).","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["running","awaiting_input","completed","needs_review","failed"]}}},"SkillSummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"version":{"type":"integer"},"runCount":{"type":"integer"},"inputs":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}}}}}},"Verification":{"type":"object","properties":{"found":{"type":"boolean"},"runId":{"type":"string"},"status":{"type":"string"},"steps":{"type":"integer"},"hash":{"type":"string","nullable":true},"matches":{"type":"boolean"},"batch":{"type":"object","properties":{"id":{"type":"string"},"root":{"type":"string"},"index":{"type":"integer"},"leafCount":{"type":"integer"},"proofValid":{"type":"boolean"},"anchor":{"type":"object","nullable":true,"properties":{"sig":{"type":"string"},"cluster":{"type":"string"},"url":{"type":"string"},"memoMatches":{"type":"boolean","nullable":true}}}}}}},"VerificationNotFound":{"type":"object","properties":{"found":{"type":"boolean","enum":[false]},"runId":{"type":"string"}}}}},"paths":{"/api/v1/runs":{"post":{"summary":"Run a skill","description":"Starts a run; returns immediately with status \"running\". Send an `Idempotency-Key` header to make retries safe - the same key returns the original run instead of starting a new one.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replay-safe key; identical retries return the first response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunRequest"}}}},"responses":{"200":{"description":"Run started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunStarted"}}}},"400":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient $AEMU balance for access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Skill not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"An identical Idempotency-Key request is in progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Daily quota reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List your runs","description":"Your runs, newest first. Cursor-paginated.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size (max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from a prior response's nextCursor."}],"responses":{"200":{"description":"A page of runs","content":{"application/json":{"schema":{"type":"object","properties":{"runs":{"type":"array","items":{"$ref":"#/components/schemas/RunListItem"}},"nextCursor":{"type":"string","nullable":true}}}}}},"401":{"description":"Missing/invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/runs/{id}":{"get":{"summary":"Get a run","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}},"401":{"description":"Missing/invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Run not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/skills":{"get":{"summary":"List published skills","description":"The published catalog, newest first. Cursor-paginated.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size (max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from a prior response's nextCursor."}],"responses":{"200":{"description":"A page of the catalog","content":{"application/json":{"schema":{"type":"object","properties":{"skills":{"type":"array","items":{"$ref":"#/components/schemas/SkillSummary"}},"nextCursor":{"type":"string","nullable":true}}}}}},"401":{"description":"Missing/invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/verify/{runId}":{"get":{"summary":"Verify a receipt (public)","security":[],"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}}},"404":{"description":"No receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationNotFound"}}}}}}},"/api/batch/{id}/bundle":{"get":{"summary":"Download a proof bundle (public)","security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Self-contained, content-addressed proof bundle"},"404":{"description":"Batch not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}