{"openapi":"3.1.0","info":{"title":"API Clearinghouse","version":"0.3.0","description":"Agent-native API infrastructure. Connect to 34 external APIs through a single integration layer.","contact":{"url":"https://apiclearinghouse.com","email":"support@apiclearinghouse.com"}},"servers":[{"url":"https://api.apiclearinghouse.com","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Your clearinghouse API key (chk_live_... or chk_test_...). Sign up at https://apiclearinghouse.com"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token from /v1/auth/login"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string","description":"Machine-readable hint for agents"},"docs":{"type":"string","description":"Link to relevant documentation"}},"required":["error"]},"ApiEntry":{"type":"object","properties":{"api_name":{"type":"string"},"display_name":{"type":"string"},"category":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"free":{"type":"boolean"},"tier_required":{"type":"string","enum":["developer","pro","business","enterprise"]},"health_score":{"type":"integer","minimum":0,"maximum":100},"example_query":{"type":"string","nullable":true},"endpoints":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"method":{"type":"string"},"description":{"type":"string","nullable":true},"params":{"type":"object","additionalProperties":true}},"required":["path","method"]}}},"required":["api_name","display_name","tier_required","health_score","endpoints"]},"Team":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"ownerId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","ownerId"]},"ApiKey":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"keyPrefix":{"type":"string","example":"chk_live_"},"environment":{"type":"string","enum":["live","test"]},"label":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","keyPrefix","environment"]},"ProviderKey":{"type":"object","properties":{"apiSlug":{"type":"string","example":"the-odds"},"displayName":{"type":"string","example":"The Odds API"},"accessMode":{"type":"string","enum":["platform_managed","byok_available","byok_required"]},"status":{"type":"string","enum":["valid","invalid","unvalidated"]},"maskedKey":{"type":"string","nullable":true,"example":"****abcd"},"savedAt":{"type":"string","format":"date-time"},"lastValidatedAt":{"type":"string","format":"date-time","nullable":true}},"required":["apiSlug","displayName","accessMode","status","savedAt"]}}},"paths":{"/v1/auth/signup":{"post":{"tags":["Auth"],"summary":"Sign up","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8}},"required":["email","password"]}}}},"responses":{"201":{"description":"Account created","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"}}}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/login":{"post":{"tags":["Auth"],"summary":"Log in","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"]}}}},"responses":{"200":{"description":"Login successful","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"}}}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me":{"get":{"tags":["Account"],"summary":"Get current user profile","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"User profile","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"tier":{"type":"string"},"termsAcceptedAt":{"type":"string","format":"date-time","nullable":true}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog":{"get":{"tags":["Catalog"],"summary":"List all available APIs","description":"Returns all active APIs with endpoints, params, and health scores. Public — no auth required.","security":[],"responses":{"200":{"description":"Catalog","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiEntry"}},"total":{"type":"integer"}}}}}}}}},"/v1/call/{apiSlug}/{endpoint}":{"get":{"tags":["Proxy"],"summary":"Proxy GET call to an external API","description":"Forward a request to the named API. Query params are forwarded as-is. Requires API key.","parameters":[{"name":"apiSlug","in":"path","required":true,"schema":{"type":"string"},"description":"API slug from catalog (e.g. weather, geocoding)"},{"name":"endpoint","in":"path","required":true,"schema":{"type":"string"},"description":"Endpoint path from catalog (e.g. /current, /search)"}],"responses":{"200":{"description":"Upstream response, pass-through JSON"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan upgrade required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream error"}}},"post":{"tags":["Proxy"],"summary":"Proxy POST call to an external API","parameters":[{"name":"apiSlug","in":"path","required":true,"schema":{"type":"string"}},{"name":"endpoint","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Upstream response"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/keys":{"get":{"tags":["Keys"],"summary":"List API keys","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"API key list","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}}}}}}}},"post":{"tags":["Keys"],"summary":"Create a new API key","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","maxLength":255},"environment":{"type":"string","enum":["live","test"],"default":"live"}}}}}},"responses":{"201":{"description":"API key created — key value shown only once","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","description":"Full key — save this, it is shown only once"},"id":{"type":"string","format":"uuid"},"keyPrefix":{"type":"string"}}}}}}}}},"/v1/keys/{id}":{"delete":{"tags":["Keys"],"summary":"Revoke an API key","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Key revoked"},"404":{"description":"Key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/teams":{"get":{"tags":["Teams"],"summary":"List teams you belong to","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Team list","content":{"application/json":{"schema":{"type":"object","properties":{"teams":{"type":"array","items":{"$ref":"#/components/schemas/Team"}}}}}}}}},"post":{"tags":["Teams"],"summary":"Create a team","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":100}},"required":["name"]}}}},"responses":{"201":{"description":"Team created","content":{"application/json":{"schema":{"type":"object","properties":{"team":{"$ref":"#/components/schemas/Team"}}}}}}}}},"/v1/teams/{id}":{"get":{"tags":["Teams"],"summary":"Get team details with members and API keys","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Team detail","content":{"application/json":{"schema":{"type":"object","properties":{"team":{"$ref":"#/components/schemas/Team"},"members":{"type":"array","items":{"type":"object"}},"keys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}},"yourRole":{"type":"string","enum":["owner","admin","member"]}}}}}},"404":{"description":"Not found or not a member","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Teams"],"summary":"Update team name (owner/admin only)","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":100}},"required":["name"]}}}},"responses":{"200":{"description":"Updated team","content":{"application/json":{"schema":{"type":"object","properties":{"team":{"$ref":"#/components/schemas/Team"}}}}}}}}},"/v1/teams/{id}/members":{"post":{"tags":["Teams"],"summary":"Add a member by email (owner/admin only)","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["admin","member"],"default":"member"}},"required":["email"]}}}},"responses":{"201":{"description":"Member added"},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/teams/{id}/members/{memberId}":{"put":{"tags":["Teams"],"summary":"Update member role (owner only)","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"memberId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["admin","member"]}},"required":["role"]}}}},"responses":{"200":{"description":"Role updated"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Teams"],"summary":"Remove member (owner/admin/self)","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"memberId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Member removed"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/status":{"get":{"tags":["Billing"],"summary":"Get current billing status and tier","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Billing status","content":{"application/json":{"schema":{"type":"object","properties":{"tier":{"type":"string","enum":["developer","pro","business","enterprise"]},"tierDisplay":{"type":"string"},"plan":{"type":"object","nullable":true},"billingEnabled":{"type":"boolean"}}}}}}}}},"/v1/billing/checkout":{"post":{"tags":["Billing"],"summary":"Create a Stripe Checkout session","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tier":{"type":"string","enum":["pro","business"]},"interval":{"type":"string","enum":["monthly","yearly"],"default":"monthly"},"teamId":{"type":"string","format":"uuid","description":"Subscribe on behalf of a team (admin/owner only)"}},"required":["tier"]}}}},"responses":{"201":{"description":"Checkout session created","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"url":{"type":"string","format":"uri"}}}}}}}}},"/v1/user/keys":{"get":{"tags":["Provider Keys"],"summary":"List saved provider keys","description":"Returns all saved BYOK provider keys for the authenticated user, with validation status.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Provider key list","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProviderKey"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"EMAIL_NOT_VERIFIED — email address must be verified before accessing provider keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/user/keys/{api_slug}":{"get":{"tags":["Provider Keys"],"summary":"Get saved provider key for an API","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"api_slug","in":"path","required":true,"schema":{"type":"string"},"description":"API slug (e.g. the-odds)"}],"responses":{"200":{"description":"Provider key status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderKey"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"EMAIL_NOT_VERIFIED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No key saved for this API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Provider Keys"],"summary":"Save or rotate a provider key","description":"Encrypts and stores your API key for the given provider. Triggers async validation. Replaces any existing key.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"api_slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","description":"Your provider API key"}},"required":["key"]}}}},"responses":{"201":{"description":"Key saved — async validation will run in the background","content":{"application/json":{"schema":{"type":"object","properties":{"apiSlug":{"type":"string"},"status":{"type":"string","enum":["unvalidated"]},"maskedKey":{"type":"string","example":"****abcd"},"savedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Validation error (e.g. empty key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"EMAIL_NOT_VERIFIED or BYOK_NOT_AVAILABLE for this API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Provider Keys"],"summary":"Remove a saved provider key","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"api_slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Key removed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"EMAIL_NOT_VERIFIED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No key saved for this API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/apis/request":{"post":{"tags":["Catalog"],"summary":"Request a new API be added to the catalog","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"apiName":{"type":"string","maxLength":255,"description":"Name or slug of the API you want"},"description":{"type":"string","description":"What the API provides"},"useCase":{"type":"string","description":"Your intended use case"}},"required":["apiName"]}}}},"responses":{"201":{"description":"Request recorded"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"tags":[{"name":"Auth","description":"Signup, login, and token management"},{"name":"Account","description":"User profile and settings"},{"name":"Catalog","description":"Discover available APIs"},{"name":"Proxy","description":"Forward requests to external APIs"},{"name":"Keys","description":"API key management"},{"name":"Teams","description":"Team and multi-user management"},{"name":"Billing","description":"Subscription and billing management"},{"name":"Provider Keys","description":"Bring Your Own Key — save and manage your own provider API keys"}]}