{"openapi":"3.1.0","info":{"title":"uEngage Business API","version":"0.1.0","description":"Read-only access to the business catalog. Returns a base envelope ({id, parent_id}) plus optional groups (profile, gst, payment_gateway) selected via the `groups` query parameter.","license":{"name":"Proprietary"}},"servers":[{"url":"https://api.platform.uengage.io","description":"Production"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth2 Bearer JWT, RS256-signed by the auth service. Verify against the JWKS at `/auth/business/jwks.json`. Service-to-service callers mint via `POST /auth/business/oauth/token` with `grant_type=client_credentials`."}},"schemas":{"BusinessProfile":{"type":"object","properties":{"name":{"type":"string","nullable":true,"example":"Acme"}},"required":["name"]},"BusinessParent":{"type":"object","nullable":true,"properties":{"id":{"type":"integer","example":42},"profile":{"$ref":"#/components/schemas/BusinessProfile"}},"required":["id","profile"],"description":"Direct parent business (single level), or null if root."},"BusinessGst":{"type":"object","properties":{"state":{"type":"string","nullable":true,"example":"KA"},"gstin":{"type":"string","nullable":true,"example":"29ABCDE1234F1Z5"}},"required":["state","gstin"]},"BusinessPaymentGateway":{"type":"object","properties":{"razorpay":{"type":"object","properties":{"key":{"type":"string","nullable":true},"secret":{"type":"string","nullable":true}},"required":["key","secret"]}},"required":["razorpay"]},"BusinessRecord":{"type":"object","properties":{"id":{"type":"integer","example":123},"parent":{"$ref":"#/components/schemas/BusinessParent"},"profile":{"$ref":"#/components/schemas/BusinessProfile"},"gst":{"$ref":"#/components/schemas/BusinessGst"},"payment_gateway":{"$ref":"#/components/schemas/BusinessPaymentGateway"}},"required":["id","parent"]},"ApiError":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"issues":{"type":"array","items":{"nullable":true}}},"required":["error"],"description":"Standard error envelope. `error` is a stable machine-readable code; `message` is a human-readable hint; `issues` (when present) is a Zod validation issue list."}},"parameters":{}},"paths":{"/v1/businesses":{"get":{"tags":["business"],"summary":"List businesses (filtered by ids)","description":"Returns matched records in input order. Unknown ids are silently dropped. Capped at 100 ids per request. `ids` is required today; future filters may be added (tenant, parent_id, pagination).","parameters":[{"schema":{"type":"string","example":"123,124,125"},"required":true,"name":"ids","in":"query"},{"schema":{"type":"string","example":"profile"},"required":false,"name":"groups","in":"query"}],"responses":{"200":{"description":"Array of matched records","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BusinessRecord"}}}}},"400":{"description":"Invalid query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Auth headers presented but invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Caller is not authorized for any requested group","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/businesses/{id}":{"get":{"tags":["business"],"summary":"Get a business by id","description":"Returns the base envelope plus any requested groups the caller is authorized for. Unauthorized groups are silently dropped; 403 if the resolved group set is empty.","parameters":[{"schema":{"type":"string","pattern":"^\\d+$","example":"123"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","example":"profile,gst"},"required":false,"name":"groups","in":"query"}],"responses":{"200":{"description":"Matched business record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessRecord"}}}},"400":{"description":"Invalid path or query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Auth headers presented but invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Caller is not authorized for any requested group","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Business id does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}