{"openapi":"3.1.0","info":{"title":"Loup REST API","version":"1.0.0","description":"Programmatic access to installs, usage events, webhooks, buyer install-token runtime invoke, and MCP-backed local agent use.","contact":{"name":"Loup support","email":"support@selrgroup.com.au","url":"https://louphq.com/contact"},"license":{"name":"Public API - usage governed by the Loup Terms of Service","url":"https://louphq.com/legal/terms"}},"servers":[{"url":"https://louphq.com","description":"Current deployment"}],"security":[{"BearerAuth":[]}],"tags":[{"name":"Account","description":"Bearer token verification + account metadata"},{"name":"Installs","description":"List installs of your packs"},{"name":"Usage","description":"Read usage events for your packs"},{"name":"Runtime","description":"Buyer install-token APIs used by @louphq/mcp"},{"name":"Marketplace","description":"Public marketplace search for agents"},{"name":"Skills","description":"Install-token-gated Skill Pack file delivery"}],"paths":{"/api/v1/me":{"get":{"tags":["Account"],"summary":"Verify the bearer token","description":"Returns the account id, granted scopes, and API key id for the authenticated token.","operationId":"getMe","responses":{"200":{"description":"Token is valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"},"example":{"account_id":"acc_3f2a4b5c6d7e","scopes":["read:installs","read:usage"],"key_id":"key_abc123"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/installs":{"get":{"tags":["Installs"],"summary":"List installs of your packs","description":"Returns installs of skill packs published by the authenticated account. Cursor-paginated.","operationId":"listInstalls","parameters":[{"name":"pack_id","in":"query","schema":{"type":"string"},"description":"Filter to one pack"},{"name":"status","in":"query","schema":{"type":"string","enum":["active","trialing","canceled"]},"description":"Filter by lifecycle status"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Cursor from a previous response"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Page size (max 100)"}],"responses":{"200":{"description":"Page of installs","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Install"}},"next_cursor":{"type":"string","nullable":true,"description":"Pass back as `cursor` to fetch the next page. Absent when no next page."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/usage":{"get":{"tags":["Usage"],"summary":"Recent usage events","description":"Returns usage events for the authenticated account's packs. Default window is the last 7 days.","operationId":"listUsage","parameters":[{"name":"pack_id","in":"query","required":false,"schema":{"type":"string"},"description":"Optional filter to one pack"},{"name":"event_type","in":"query","schema":{"type":"string","enum":["skill.invoked","skill.success","skill.error"]}},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601"},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":200}}],"responses":{"200":{"description":"Page of usage events","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UsageEvent"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/runtime/installs":{"get":{"tags":["Runtime"],"summary":"List the purchased skill for an install token","description":"Returns the active Skill Pack connected to the buyer install token. Used by @louphq/mcp list_installed_skills.","operationId":"listRuntimeInstalls","security":[{"InstallTokenAuth":[]}],"responses":{"200":{"description":"Installed skill for this token","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RuntimeInstall"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/runtime/invoke":{"post":{"tags":["Runtime"],"summary":"Invoke a purchased Skill Pack","description":"Hosted execution is parked. Skills run locally in the buyer's agent; this route currently returns 410 with install guidance unless the hosted_runtime feature flag is enabled.","operationId":"invokeRuntimeSkill","security":[{"InstallTokenAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string"},"message_text":{"type":"string"}}},"example":{"prompt":"Draft a launch hook"}}}},"responses":{"200":{"description":"Skill invocation result when hosted runtime is enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuntimeInvokeResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"410":{"description":"Hosted runtime is disabled; install and run the Skill Pack locally","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuntimeDisabled"}}}},"422":{"$ref":"#/components/responses/RuntimeError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/runtime/whats-new":{"get":{"tags":["Runtime"],"summary":"Current version and update feed","description":"Returns the current purchased Skill Pack version and conservative update feed for @louphq/mcp whats_new.","operationId":"runtimeWhatsNew","security":[{"InstallTokenAuth":[]}],"responses":{"200":{"description":"Current skill update feed","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/RuntimeWhatsNew"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/marketplace/search":{"get":{"tags":["Marketplace"],"summary":"Search public Skill Packs","description":"Public marketplace search used by @louphq/mcp browse_marketplace. Returns pack URLs and install command hints.","operationId":"searchMarketplace","security":[],"parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":200},"description":"Search terms. Empty or overlong queries return an empty result set."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":25,"default":12},"description":"Maximum results"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceSearchResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/skills/download":{"get":{"tags":["Skills"],"summary":"Download the purchased Skill Pack snapshot","description":"Streams the approved snapshot tarball for the Skill Pack attached to the buyer install token. The @louphq/install CLI calls this endpoint.","operationId":"downloadSkillSnapshot","security":[{"InstallTokenAuth":[]}],"parameters":[{"name":"version","in":"query","schema":{"type":"string"},"description":"Optional approved version. Defaults to the latest approved version for this creator and slug."}],"responses":{"200":{"description":"Gzipped tarball of the real repo files","headers":{"X-Loup-Version":{"schema":{"type":"string"},"description":"Downloaded Skill Pack version"},"X-Content-Sha256":{"schema":{"type":"string"},"description":"Expected sha256 digest for integrity checks"}},"content":{"application/gzip":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/ServerError"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Mint a key from /dashboard/creator/keys. SHA-256 hashed at rest. Pass as `Authorization: Bearer plat_<your-key>`. Plaintext is shown ONCE at mint time — save it immediately."},"InstallTokenAuth":{"type":"http","scheme":"bearer","description":"Mint an install token from /dashboard/buyer for a purchased install. Pass as `Authorization: Bearer loupit_<token>`. Plaintext is shown once."}},"schemas":{"Account":{"type":"object","required":["account_id","scopes","key_id"],"properties":{"account_id":{"type":"string","example":"acc_3f2a4b5c6d7e"},"scopes":{"type":"array","items":{"type":"string","enum":["read:installs","read:usage","read:payouts","write:webhooks","admin"]}},"key_id":{"type":"string","example":"key_abc123"}}},"Install":{"type":"object","required":["id","skill_pack_id","status","created_at"],"properties":{"id":{"type":"string","example":"ins_a1b2c3d4"},"skill_pack_id":{"type":"string","example":"pck_voice_graded_writer"},"status":{"type":"string","enum":["active","trialing","canceled"]},"channel":{"type":"string","enum":["telegram","slack","whatsapp","google_chat"],"nullable":true},"installed_version":{"type":"string","nullable":true},"current_period_end":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"invocation_count":{"type":"integer","minimum":0}}},"UsageEvent":{"type":"object","required":["id","occurred_at","event_type","install_id"],"properties":{"id":{"type":"string"},"occurred_at":{"type":"string","format":"date-time"},"event_type":{"type":"string"},"install_id":{"type":"string"},"payload":{"type":"object","additionalProperties":true,"nullable":true},"llm_tokens_used":{"type":"integer","minimum":0,"nullable":true},"llm_cost_usd":{"type":"number","nullable":true}}},"RuntimeInstall":{"type":"object","required":["install_id","status","creator","slug","name","version"],"properties":{"install_id":{"type":"string"},"status":{"type":"string","enum":["active","trialing"]},"creator":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"version":{"type":"string"},"description":{"type":"string"},"local":{"type":"boolean"},"hosted":{"type":"boolean"}}},"RuntimeDisabled":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"hosted_runtime_disabled"},"message":{"type":"string"},"retryable":{"type":"boolean","const":false}}}}},"RuntimeInvokeResponse":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","required":["reply_text","llm_tokens_used","llm_cost_usd","duration_ms","client_name"],"properties":{"reply_text":{"type":"string"},"llm_tokens_used":{"type":"integer"},"llm_cost_usd":{"type":"number"},"duration_ms":{"type":"integer"},"client_name":{"type":"string","enum":["echo","claude","e2b"]},"events":{"type":"array","items":{"type":"object","additionalProperties":true}},"skill":{"$ref":"#/components/schemas/RuntimeSkill"}}}}},"RuntimeSkill":{"type":"object","required":["creator","slug","name","version"],"properties":{"creator":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"version":{"type":"string"}}},"RuntimeWhatsNew":{"type":"object","required":["skill","items"],"properties":{"skill":{"$ref":"#/components/schemas/RuntimeSkill"},"items":{"type":"array","items":{"type":"object","required":["type","title","body"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"}}}},"feed":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"MarketplaceSearchResponse":{"type":"object","required":["results","query"],"properties":{"query":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceResult"}}}},"MarketplaceResult":{"type":"object","required":["creator","slug","name","pricing_model","url","install_command"],"properties":{"creator":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"pricing_model":{"type":"string"},"url":{"type":"string","format":"uri"},"install_command":{"type":"string"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid bearer token","code":"UNAUTHORIZED"}}}},"RateLimited":{"description":"Rate limit exceeded for the authenticated tier","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"rate limit exceeded","retry_after_seconds":38}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not found"}}}},"Conflict":{"description":"Resource is not ready for this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"your files are still being prepared"}}}},"ServerError":{"description":"Upstream or server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"snapshot fetch failed"}}}},"RuntimeError":{"description":"Runtime rejected or failed the invocation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"spend cap exceeded","code":"spend_cap_exceeded"}}}}}}}