{"openapi":"3.1.0","info":{"title":"Clankerbay API","version":"1.0.0","summary":"Platform API for the Clankerbay agent marketplace.","description":"Versioned REST API for authentication, discovery, credentials, balances and billing.\nProvider endpoints are called through the gateway at `/gateway/{namespace}/{path}`.\n\nAll errors use the envelope `{\"error\": {\"code\", \"message\", ...}}`.\nThis document is the contract shared by the Laravel application, the Go\ngateway and the Go CLI (built-in `clankerbay` namespace).\n","contact":{"email":"support@clankerbay.com"},"x-clankerbay-schema-version":"1.0.0"},"servers":[{"url":"https://clankerbay.hxx.li/api/v1"}],"tags":[{"name":"auth"},{"name":"discovery"},{"name":"account"},{"name":"keys"},{"name":"gateway"}],"security":[{"agentToken":[]}],"paths":{"/pow":{"get":{"operationId":"getPowParameters","x-cli-command":"pow","tags":["auth"],"summary":"Proof-of-work parameters and server time","security":[],"responses":{"200":{"description":"Parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PowParameters"}}}}}}},"/auth/signup":{"post":{"operationId":"signup","tags":["auth"],"summary":"Create an account and receive an agent token","security":[{"proofOfWork":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","email","password","accept_terms"],"properties":{"name":{"type":"string","maxLength":100},"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":10},"accept_terms":{"type":"boolean","const":true},"token_name":{"type":"string","maxLength":100}}}}}},"responses":{"201":{"$ref":"#/components/responses/TokenIssued"},"401":{"$ref":"#/components/responses/PowRequired"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/auth/signin":{"post":{"operationId":"signin","tags":["auth"],"summary":"Exchange email and password for an agent token","security":[{"proofOfWork":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string"},"token_name":{"type":"string","maxLength":100}}}}}},"responses":{"200":{"$ref":"#/components/responses/TokenIssued"},"401":{"description":"Invalid credentials or missing proof of work","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/auth/signout":{"post":{"operationId":"signout","tags":["auth"],"summary":"Revoke the calling token","responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"type":"object","properties":{"revoked":{"type":"boolean"}}}}}}}}},"/search":{"get":{"operationId":"search","tags":["discovery"],"summary":"Search capabilities by intent, provider, namespace or command","description":"Anonymous callers must send a proof of work (scope `search`).","security":[{"agentToken":[]},{"proofOfWork":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","maxLength":200}},{"name":"namespace","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Results","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Capability"}}}}}}},"401":{"$ref":"#/components/responses/PowRequired"}}}},"/namespaces":{"get":{"operationId":"listNamespaces","tags":["discovery"],"summary":"List namespaces","security":[],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"description":"Namespaces","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Namespace"}},"meta":{"$ref":"#/components/schemas/PageMeta"}}}}}}}}},"/namespaces/{namespace}":{"get":{"operationId":"getNamespace","tags":["discovery"],"summary":"Namespace details and commands","security":[],"parameters":[{"$ref":"#/components/parameters/Namespace"}],"responses":{"200":{"description":"Namespace","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Namespace"},{"type":"object","properties":{"description":{"type":["string","null"]},"commands":{"type":"array","items":{"$ref":"#/components/schemas/Capability"}}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/namespaces/{namespace}/openapi.json":{"get":{"operationId":"getNamespaceOpenapi","tags":["discovery"],"summary":"OpenAPI document for clients","description":"The provider's registered schema with `servers` pointing at the gateway, the\nClankerbay bearer token as the only security scheme, and per-operation\n`x-clankerbay-command`, `x-clankerbay-price` and `x-cli-positional`.\n`info.x-clankerbay-schema-version` and `info.x-clankerbay-schema-hash`\nidentify the version. Supports `If-None-Match`.\n","security":[],"parameters":[{"$ref":"#/components/parameters/Namespace"},{"name":"If-None-Match","in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"OpenAPI document","headers":{"ETag":{"schema":{"type":"string"}},"X-Clankerbay-Schema-Version":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"304":{"description":"Not modified"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/account":{"get":{"operationId":"whoami","tags":["account"],"summary":"The account and token in use","responses":{"200":{"description":"Account","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"$ref":"#/components/schemas/User"},"token":{"$ref":"#/components/schemas/AgentKey"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"}}}},"/account/balance":{"get":{"operationId":"getBalance","tags":["account"],"summary":"Subscription and prepaid credit balances","description":"Requires scope `account:read`.","responses":{"200":{"description":"Balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"}}}}}}},"/account/usage":{"get":{"operationId":"listUsage","tags":["account"],"summary":"Usage records with credit source","parameters":[{"name":"namespace","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["success","upstream_error","timeout","connection_error"]}},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"description":"Usage","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UsageRecord"}},"meta":{"$ref":"#/components/schemas/PageMeta"}}}}}}}}},"/account/spending-controls":{"get":{"operationId":"getSpendingControls","tags":["account"],"summary":"Account and token spending limits","responses":{"200":{"description":"Limits","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/billing/history":{"get":{"operationId":"getBillingHistory","tags":["account"],"summary":"Charges, refunds and invoice links","responses":{"200":{"description":"History","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["charge","refund"]},"number":{"type":"string"},"description":{"type":"string"},"amount_cents":{"type":"integer"},"currency":{"type":"string"},"status":{"type":"string"},"date":{"type":"string","format":"date-time"},"invoice_url":{"type":"string","format":"uri"}}}}}}}}}}}},"/subscription":{"get":{"operationId":"getSubscription","tags":["account"],"summary":"Current subscription plan","responses":{"200":{"description":"Subscription","content":{"application/json":{"schema":{"type":"object","properties":{"subscription":{"type":["object","null"],"properties":{"plan":{"type":"string"},"status":{"type":"string"},"monthly_credits":{"type":"integer"},"price_cents":{"type":"integer"},"current_period_end":{"type":"string","format":"date-time"},"cancel_at_period_end":{"type":"boolean"},"pending_plan":{"type":["string","null"]}}}}}}}}}}},"/agent-keys":{"get":{"operationId":"listAgentKeys","tags":["keys"],"summary":"List agent tokens (scope keys:manage)","responses":{"200":{"description":"Keys","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentKey"}}}}}}}}},"post":{"operationId":"createAgentKey","tags":["keys"],"summary":"Create an agent token","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":100},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/Scope"}},"expires_in_days":{"type":"integer","minimum":1},"per_call_limit":{"type":"integer","minimum":0},"daily_cap":{"type":"integer","minimum":0},"monthly_cap":{"type":"integer","minimum":0}}}}}},"responses":{"201":{"description":"Created. `token` is shown only once.","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/AgentKey"},"token":{"type":"string"}}}}}}}}},"/agent-keys/{id}/rotate":{"post":{"operationId":"rotateAgentKey","tags":["keys"],"summary":"Rotate an agent token","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Rotated. The previous secret is revoked.","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/AgentKey"},"token":{"type":"string"}}}}}}}}},"/agent-keys/{id}":{"delete":{"operationId":"revokeAgentKey","tags":["keys"],"summary":"Revoke an agent token","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"type":"object","properties":{"revoked":{"type":"boolean"}}}}}}}}},"/gateway/{namespace}/{path}":{"get":{"operationId":"callProvider","tags":["gateway"],"summary":"Call a provider endpoint (any HTTP method)","description":"Served by the Go gateway. The method and path select an operation of the\nnamespace's active schema. Requires scope `gateway:call`. The provider's\nstatus code and body are returned unchanged, with metering headers.\nCharged only for 2xx/3xx provider responses.\n","parameters":[{"$ref":"#/components/parameters/Namespace"},{"name":"path","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Clankerbay-Max-Credits","in":"header","schema":{"type":"integer"}},{"name":"X-Clankerbay-Approve","in":"header","schema":{"type":"string","enum":["true"]}},{"name":"X-Clankerbay-Schema-Version","in":"header","schema":{"type":"integer"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":128}}],"responses":{"default":{"description":"The provider's response","headers":{"X-Clankerbay-Request-Id":{"schema":{"type":"string"}},"X-Clankerbay-Credits-Charged":{"schema":{"type":"integer"}},"X-Clankerbay-Credits-Subscription":{"schema":{"type":"integer"}},"X-Clankerbay-Credits-Prepaid":{"schema":{"type":"integer"}},"X-Clankerbay-Upstream-Status":{"schema":{"type":"integer"}},"X-Clankerbay-Latency-Ms":{"schema":{"type":"integer"}}}},"402":{"description":"insufficient_credits or approval_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"price_exceeds_max, schema_changed or idempotency_in_progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited, daily_cap_exceeded or monthly_cap_exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"upstream_unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"upstream_timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"agentToken":{"type":"http","scheme":"bearer","description":"Clankerbay agent token (`cbk_…`)."},"proofOfWork":{"type":"apiKey","in":"header","name":"X-Clankerbay-PoW","description":"Protocol cbpow1. nonce = hex16(unix seconds, big-endian u64) + hex16(random u64), lowercase.\ndigest = hex(HMAC-SHA256(key=\"clankerbay\", \"cbpow1:\" + scope + \":\" + nonce)).\nValid when the digest starts with `difficulty` zeros, the timestamp is within\nthe window, and the nonce has not been used before.\n"}},"parameters":{"Namespace":{"name":"namespace","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z][a-z0-9-]{1,63}$"}},"Page":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},"PerPage":{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}},"responses":{"TokenIssued":{"description":"Token issued. Shown only once.","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"$ref":"#/components/schemas/User"},"token":{"type":"string"},"token_id":{"type":"integer"}}}}}},"PowRequired":{"description":"Missing, invalid, expired or replayed proof of work","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"}]}}}},"Unauthenticated":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"pow":{"$ref":"#/components/schemas/PowParameters"}}}}},"PowParameters":{"type":"object","properties":{"algorithm":{"type":"string","const":"HMAC-SHA256"},"version":{"type":"string","const":"cbpow1"},"key":{"type":"string","const":"clankerbay"},"message":{"type":"string"},"difficulty":{"type":"integer"},"window_seconds":{"type":"integer"},"future_skew_seconds":{"type":"integer"},"server_time":{"type":"integer"},"header":{"type":"string"}}},"Scope":{"type":"string","enum":["gateway:call","account:read","keys:manage","provider:manage"]},"User":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"is_provider":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"AgentKey":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/Scope"}},"status":{"type":"string","enum":["active","revoked","expired"]},"per_call_limit":{"type":["integer","null"]},"daily_cap":{"type":["integer","null"]},"monthly_cap":{"type":["integer","null"]},"created_at":{"type":"string","format":"date-time"},"last_used_at":{"type":["string","null"],"format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"}}},"Namespace":{"type":"object","properties":{"namespace":{"type":"string"},"name":{"type":"string"},"summary":{"type":["string","null"]},"provider":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"category":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"status":{"type":"string"},"schema_version":{"type":["integer","null"]},"openapi_url":{"type":"string","format":"uri"},"gateway_url":{"type":["string","null"],"format":"uri"}}},"Capability":{"type":"object","properties":{"namespace":{"type":"string"},"service":{"type":"string"},"provider":{"type":"string"},"command":{"type":"string"},"summary":{"type":["string","null"]},"method":{"type":"string"},"path":{"type":"string"},"price_credits":{"type":"integer"},"required_inputs":{"type":"array","items":{"type":"string"}},"access":{"type":"object"},"invoke":{"type":"string","description":"Example CLI invocation"}}},"Balance":{"type":"object","properties":{"subscription_credits":{"type":"integer"},"prepaid_credits":{"type":"integer"},"total_credits":{"type":"integer"},"subscription_credits_expire_at":{"type":["string","null"],"format":"date-time"},"charge_order":{"type":"array","items":{"type":"string"},"example":["subscription","prepaid"]},"plan":{"type":["string","null"]}}},"UsageRecord":{"type":"object","properties":{"request_id":{"type":"string"},"requested_at":{"type":"string","format":"date-time"},"namespace":{"type":"string"},"command":{"type":["string","null"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"string"},"http_status":{"type":["integer","null"]},"latency_ms":{"type":"integer"},"credits_charged":{"type":"integer"},"credits_from_subscription":{"type":"integer"},"credits_from_prepaid":{"type":"integer"}}},"PageMeta":{"type":"object","properties":{"page":{"type":"integer"},"last_page":{"type":"integer"},"total":{"type":"integer"}}}}}}