From 5466fcf843f4de49d148e1493d1c01aea93ac9fc Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Fri, 1 May 2026 19:27:43 +0530 Subject: [PATCH 1/3] docs(docs): migrate GET /api/credits/get + GET /api/subscription/status MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Group 3 (Billing read) of the chat→api migration plan. Documents the two account-scoped read endpoints chat's usePayment hook depends on. Co-Authored-By: Claude Opus 4.7 (1M context) --- api-reference/billing/credits.mdx | 4 + api-reference/billing/subscription-status.mdx | 4 + api-reference/openapi/billing.json | 166 ++++++++++++++++++ docs.json | 7 + 4 files changed, 181 insertions(+) create mode 100644 api-reference/billing/credits.mdx create mode 100644 api-reference/billing/subscription-status.mdx create mode 100644 api-reference/openapi/billing.json diff --git a/api-reference/billing/credits.mdx b/api-reference/billing/credits.mdx new file mode 100644 index 0000000..f85decd --- /dev/null +++ b/api-reference/billing/credits.mdx @@ -0,0 +1,4 @@ +--- +title: 'Get Credits' +openapi: '/api-reference/openapi/billing.json GET /api/credits/get' +--- diff --git a/api-reference/billing/subscription-status.mdx b/api-reference/billing/subscription-status.mdx new file mode 100644 index 0000000..2035fb6 --- /dev/null +++ b/api-reference/billing/subscription-status.mdx @@ -0,0 +1,4 @@ +--- +title: 'Subscription Status' +openapi: '/api-reference/openapi/billing.json GET /api/subscription/status' +--- diff --git a/api-reference/openapi/billing.json b/api-reference/openapi/billing.json new file mode 100644 index 0000000..681c30e --- /dev/null +++ b/api-reference/openapi/billing.json @@ -0,0 +1,166 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "Recoup API - Billing", + "description": "API documentation for the Recoup platform - an AI agent platform for the music industry", + "license": { + "name": "MIT" + }, + "version": "1.0.0" + }, + "servers": [ + { + "url": "https://recoup-api.vercel.app" + } + ], + "paths": { + "/api/credits/get": { + "get": { + "description": "Returns the credit balance for the given account, automatically resetting the balance when the account is on a refill cycle (monthly cadence or just-activated subscription). Honors both account-level and organization-level Stripe subscriptions when deciding whether the refill should use the pro tier. No authentication required.", + "parameters": [ + { + "name": "accountId", + "in": "query", + "required": true, + "description": "The Recoup account ID whose credits should be returned.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Credits retrieved (and refilled if eligible).", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreditsGetResponse" + } + } + } + }, + "400": { + "description": "Validation or upstream error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BillingErrorResponse" + } + } + } + } + } + } + }, + "/api/subscription/status": { + "get": { + "description": "Returns whether the given account is on a pro subscription. An account is considered pro if it has an active Stripe subscription itself, or if any of its organizations does. No authentication required.", + "parameters": [ + { + "name": "accountId", + "in": "query", + "required": true, + "description": "The Recoup account ID whose pro status should be returned.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Pro status retrieved.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SubscriptionStatusResponse" + } + } + } + }, + "400": { + "description": "Validation or upstream error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BillingErrorResponse" + } + } + } + } + } + } + } + }, + "components": { + "schemas": { + "CreditsGetResponse": { + "type": "object", + "required": [ + "data" + ], + "properties": { + "data": { + "oneOf": [ + { + "$ref": "#/components/schemas/CreditsUsage" + }, + { + "type": "null" + } + ], + "description": "The account's credits usage row, or null when the account has no credits row yet." + } + } + }, + "CreditsUsage": { + "type": "object", + "required": [ + "account_id", + "remaining_credits" + ], + "properties": { + "account_id": { + "type": "string", + "description": "The Recoup account ID." + }, + "remaining_credits": { + "type": "number", + "description": "Remaining credits for the account." + }, + "timestamp": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "ISO timestamp of the last credits refill." + } + } + }, + "SubscriptionStatusResponse": { + "type": "object", + "required": [ + "isPro" + ], + "properties": { + "isPro": { + "type": "boolean", + "description": "True when the account or any of its organizations has an active Stripe subscription." + } + } + }, + "BillingErrorResponse": { + "type": "object", + "required": [ + "message" + ], + "properties": { + "message": { + "type": "string", + "description": "Human-readable error message." + } + } + } + } + } +} diff --git a/docs.json b/docs.json index 0ea3137..05573ed 100644 --- a/docs.json +++ b/docs.json @@ -322,6 +322,13 @@ "api-reference/subscriptions/sessions-create" ] }, + { + "group": "Billing", + "pages": [ + "api-reference/billing/credits", + "api-reference/billing/subscription-status" + ] + }, { "group": "Admins", "pages": [ From c818bbbb0680331558c686b2da1007034f57387a Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Fri, 1 May 2026 19:43:11 +0530 Subject: [PATCH 2/3] docs(docs): adopt REST conventions for billing reads MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Renames the documented paths to follow api repo conventions and documents the auth requirement (apiKey or bearer): - /api/credits/get → /api/credits - /api/subscription/status → /api/subscriptions/status Adds securitySchemes (bearerAuth + apiKeyAuth) and 401/500 response shapes; drops the `accountId` query parameter — the api now derives the account from the auth context. Co-Authored-By: Claude Opus 4.7 (1M context) --- api-reference/billing/credits.mdx | 2 +- api-reference/billing/subscription-status.mdx | 2 +- api-reference/openapi/billing.json | 76 +++++++++++++------ 3 files changed, 53 insertions(+), 27 deletions(-) diff --git a/api-reference/billing/credits.mdx b/api-reference/billing/credits.mdx index f85decd..279d78d 100644 --- a/api-reference/billing/credits.mdx +++ b/api-reference/billing/credits.mdx @@ -1,4 +1,4 @@ --- title: 'Get Credits' -openapi: '/api-reference/openapi/billing.json GET /api/credits/get' +openapi: '/api-reference/openapi/billing.json GET /api/credits' --- diff --git a/api-reference/billing/subscription-status.mdx b/api-reference/billing/subscription-status.mdx index 2035fb6..da8b851 100644 --- a/api-reference/billing/subscription-status.mdx +++ b/api-reference/billing/subscription-status.mdx @@ -1,4 +1,4 @@ --- title: 'Subscription Status' -openapi: '/api-reference/openapi/billing.json GET /api/subscription/status' +openapi: '/api-reference/openapi/billing.json GET /api/subscriptions/status' --- diff --git a/api-reference/openapi/billing.json b/api-reference/openapi/billing.json index 681c30e..959141f 100644 --- a/api-reference/openapi/billing.json +++ b/api-reference/openapi/billing.json @@ -14,18 +14,15 @@ } ], "paths": { - "/api/credits/get": { + "/api/credits": { "get": { - "description": "Returns the credit balance for the given account, automatically resetting the balance when the account is on a refill cycle (monthly cadence or just-activated subscription). Honors both account-level and organization-level Stripe subscriptions when deciding whether the refill should use the pro tier. No authentication required.", - "parameters": [ + "description": "Returns the credit balance for the authenticated account, automatically resetting the balance when the account is on a refill cycle (monthly cadence or just-activated subscription). Honors both account-level and organization-level Stripe subscriptions when deciding whether the refill should use the pro tier.", + "security": [ { - "name": "accountId", - "in": "query", - "required": true, - "description": "The Recoup account ID whose credits should be returned.", - "schema": { - "type": "string" - } + "apiKeyAuth": [] + }, + { + "bearerAuth": [] } ], "responses": { @@ -39,8 +36,18 @@ } } }, - "400": { - "description": "Validation or upstream error.", + "401": { + "description": "Authentication required or invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BillingErrorResponse" + } + } + } + }, + "500": { + "description": "Internal server error.", "content": { "application/json": { "schema": { @@ -52,18 +59,15 @@ } } }, - "/api/subscription/status": { + "/api/subscriptions/status": { "get": { - "description": "Returns whether the given account is on a pro subscription. An account is considered pro if it has an active Stripe subscription itself, or if any of its organizations does. No authentication required.", - "parameters": [ + "description": "Returns whether the authenticated account is on a pro subscription. An account is considered pro if it has an active Stripe subscription itself, or if any of its organizations does.", + "security": [ { - "name": "accountId", - "in": "query", - "required": true, - "description": "The Recoup account ID whose pro status should be returned.", - "schema": { - "type": "string" - } + "apiKeyAuth": [] + }, + { + "bearerAuth": [] } ], "responses": { @@ -77,8 +81,18 @@ } } }, - "400": { - "description": "Validation or upstream error.", + "401": { + "description": "Authentication required or invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BillingErrorResponse" + } + } + } + }, + "500": { + "description": "Internal server error.", "content": { "application/json": { "schema": { @@ -92,6 +106,18 @@ } }, "components": { + "securitySchemes": { + "bearerAuth": { + "type": "http", + "scheme": "bearer" + }, + "apiKeyAuth": { + "type": "apiKey", + "in": "header", + "name": "x-api-key", + "description": "Your Recoup API key. [Learn more](/quickstart#api-keys)." + } + }, "schemas": { "CreditsGetResponse": { "type": "object", @@ -108,7 +134,7 @@ "type": "null" } ], - "description": "The account's credits usage row, or null when the account has no credits row yet." + "description": "The authenticated account's credits usage row, or null when the account has no credits row yet." } } }, From 15931c92f836317d0e6933f412fc02115db970a3 Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Fri, 1 May 2026 19:52:32 +0530 Subject: [PATCH 3/3] docs(docs): rename subscription read to GET /api/subscription (singular) Co-Authored-By: Claude Opus 4.7 (1M context) --- api-reference/billing/subscription-status.mdx | 2 +- api-reference/openapi/billing.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/api-reference/billing/subscription-status.mdx b/api-reference/billing/subscription-status.mdx index da8b851..7943367 100644 --- a/api-reference/billing/subscription-status.mdx +++ b/api-reference/billing/subscription-status.mdx @@ -1,4 +1,4 @@ --- title: 'Subscription Status' -openapi: '/api-reference/openapi/billing.json GET /api/subscriptions/status' +openapi: '/api-reference/openapi/billing.json GET /api/subscription' --- diff --git a/api-reference/openapi/billing.json b/api-reference/openapi/billing.json index 959141f..2172a03 100644 --- a/api-reference/openapi/billing.json +++ b/api-reference/openapi/billing.json @@ -59,7 +59,7 @@ } } }, - "/api/subscriptions/status": { + "/api/subscription": { "get": { "description": "Returns whether the authenticated account is on a pro subscription. An account is considered pro if it has an active Stripe subscription itself, or if any of its organizations does.", "security": [