@genlobe/mcp-server 3.1.8 → 3.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +46 -68
- package/dist/index.js +148 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,34 +1,38 @@
|
|
|
1
1
|
# Genlobe MCP Server
|
|
2
2
|
|
|
3
|
-
A Model Context Protocol (MCP) server that
|
|
3
|
+
A Model Context Protocol (MCP) server that documents the [Genlobe](https://genlobe.ai) API so AI assistants in your IDE (Cursor, Claude Code, Windsurf, Claude Desktop, …) can build real clients against it — without hallucinating endpoints, shapes, or auth headers.
|
|
4
|
+
|
|
5
|
+
Paste it into your MCP config and ask your assistant *"build me a login screen"* or *"add a checkout flow"*. It will pull the right endpoints, headers, and code patterns straight from this server.
|
|
4
6
|
|
|
5
7
|
[](https://www.npmjs.com/package/@genlobe/mcp-server)
|
|
6
8
|
[](https://nodejs.org)
|
|
7
9
|
|
|
8
10
|
---
|
|
9
11
|
|
|
10
|
-
##
|
|
12
|
+
## What it documents
|
|
11
13
|
|
|
12
|
-
The Genlobe API
|
|
14
|
+
The Genlobe API has two surfaces. This server only exposes the one your end-user app should call:
|
|
13
15
|
|
|
14
|
-
| Surface | Path prefix | Auth |
|
|
15
|
-
|
|
16
|
-
| **End-user API** | `/v1/auth/*`, `/v1/agents/*`, `/v1/organizations/*`, `/v1/external-agents/*`, … | `X-API-Key` + end-user JWT |
|
|
17
|
-
|
|
|
16
|
+
| Surface | Path prefix | Auth | Documented here? |
|
|
17
|
+
|---|---|---|---|
|
|
18
|
+
| **End-user API** | `/v1/auth/*`, `/v1/agents/*`, `/v1/organizations/*`, `/v1/external-agents/*`, … | `X-API-Key` + end-user JWT | Yes |
|
|
19
|
+
| Tenant / Dashboard API | `/v1/tenant-auth/*`, `/v1/dashboard/*` | Tenant member JWT | No — by design |
|
|
18
20
|
|
|
19
|
-
|
|
21
|
+
If the assistant ever suggests calling `/v1/dashboard/...` or `/v1/tenant-auth/...` from your end-user frontend, it's wrong: those endpoints exist for tenant admins, not for the apps you build on Genlobe.
|
|
20
22
|
|
|
21
23
|
---
|
|
22
24
|
|
|
23
25
|
## Install
|
|
24
26
|
|
|
25
|
-
Pick the snippet that matches your IDE.
|
|
27
|
+
Pick the snippet that matches your IDE. Drop in your API key (get one from [genlobe.ai](https://genlobe.ai) → your Tenant Dashboard → API Keys), restart the IDE, and the `genlobe` server will appear in its MCP server list.
|
|
28
|
+
|
|
29
|
+
### Cursor / Claude Code / Windsurf
|
|
26
30
|
|
|
27
|
-
|
|
31
|
+
Edit `.cursor/mcp.json`, `~/.config/claude-code/mcp.json`, or your equivalent client config:
|
|
28
32
|
|
|
29
33
|
```json
|
|
30
34
|
{
|
|
31
|
-
"
|
|
35
|
+
"mcpServers": {
|
|
32
36
|
"genlobe": {
|
|
33
37
|
"command": "npx",
|
|
34
38
|
"args": ["-y", "@genlobe/mcp-server"],
|
|
@@ -41,7 +45,9 @@ Pick the snippet that matches your IDE.
|
|
|
41
45
|
}
|
|
42
46
|
```
|
|
43
47
|
|
|
44
|
-
### Claude Desktop
|
|
48
|
+
### Claude Desktop
|
|
49
|
+
|
|
50
|
+
Edit `claude_desktop_config.json`:
|
|
45
51
|
|
|
46
52
|
```json
|
|
47
53
|
{
|
|
@@ -58,63 +64,57 @@ Pick the snippet that matches your IDE.
|
|
|
58
64
|
}
|
|
59
65
|
```
|
|
60
66
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
> The package is published as `@genlobe/mcp-server` on the public npm registry; `npx -y` always pulls the latest version unless you pin one (`@genlobe/mcp-server@3.1.0`).
|
|
67
|
+
`npx -y` always pulls the latest version unless you pin one (`@genlobe/mcp-server@3.3.1`).
|
|
64
68
|
|
|
65
69
|
---
|
|
66
70
|
|
|
67
71
|
## Environment variables
|
|
68
72
|
|
|
69
|
-
| Variable | Required |
|
|
73
|
+
| Variable | Required | Value |
|
|
70
74
|
|---|---|---|
|
|
71
|
-
| `SAAS_API_URL` | yes |
|
|
72
|
-
| `SAAS_API_KEY` | optional |
|
|
75
|
+
| `SAAS_API_URL` | yes | `https://api-core.genlobe.ai` |
|
|
76
|
+
| `SAAS_API_KEY` | optional | Your Genlobe API key. Accepts both `pk_live_*` (public) and `sk_live_*` (secret). Without it, only the offline documentation tools work — the four live tools (`validate_credentials`, `list_end_users`, `list_oauth_providers`, `get_openapi_spec`) need it. |
|
|
73
77
|
|
|
74
78
|
`API_URL` and `API_KEY` (without the `SAAS_` prefix) are accepted as aliases for backward compatibility.
|
|
75
79
|
|
|
76
|
-
> If `SAAS_API_URL` is not set, the server falls back to `http://localhost:8001` — useful only if you're running the Genlobe backend yourself in development (see [Local development](#local-development) below). For any normal install from npm, set `SAAS_API_URL` explicitly.
|
|
77
|
-
|
|
78
80
|
---
|
|
79
81
|
|
|
80
82
|
## Tools
|
|
81
83
|
|
|
82
|
-
|
|
84
|
+
14 tools, in three groups.
|
|
83
85
|
|
|
84
|
-
### Documentation
|
|
86
|
+
### Documentation (offline, no API key needed)
|
|
85
87
|
|
|
86
|
-
| Tool |
|
|
88
|
+
| Tool | Returns |
|
|
87
89
|
|---|---|
|
|
88
|
-
| `get_api_overview` | High-level architecture
|
|
89
|
-
| `get_end_user_endpoints` |
|
|
90
|
-
| `get_request_headers` | The exact HTTP headers required for end-user requests, with examples
|
|
91
|
-
| `get_authentication_flow` | Step-by-step
|
|
92
|
-
| `get_common_patterns` |
|
|
90
|
+
| `get_api_overview` | High-level architecture, auth model, key concepts, recommended call order. **Start here.** |
|
|
91
|
+
| `get_end_user_endpoints` | Reference for every end-user endpoint, filterable by category (`authentication`, `organizations`, `subscriptions`, `billing`, `usage`, `agents`, `users`, `plans`, `ai`, `entities`, `departments`, `files`, `external_agents`). |
|
|
92
|
+
| `get_request_headers` | The exact HTTP headers required for end-user requests, with examples. |
|
|
93
|
+
| `get_authentication_flow` | Step-by-step register → login → refresh → logout, including token storage and refresh-on-401 patterns. |
|
|
94
|
+
| `get_common_patterns` | Pagination, error handling, optimistic updates, file upload, RAG queries, agent execution. |
|
|
93
95
|
| `get_sdk_template` | A ready-to-paste TypeScript SDK module (`fetch`-based, typed) covering auth, agents, organizations, files, billing. |
|
|
94
|
-
| `search_endpoints` | Keyword search across path, summary, and description
|
|
95
|
-
| `get_endpoint_details` | Full request/response schema
|
|
96
|
+
| `search_endpoints` | Keyword search across path, summary, and description. |
|
|
97
|
+
| `get_endpoint_details` | Full request/response schema for a specific `(method, path)`. |
|
|
96
98
|
|
|
97
|
-
### Live
|
|
99
|
+
### Live (require `SAAS_API_KEY`)
|
|
98
100
|
|
|
99
|
-
| Tool |
|
|
101
|
+
| Tool | Does |
|
|
100
102
|
|---|---|
|
|
101
103
|
| `validate_credentials` | Probes the API with the configured key. Reports the detected key type (`pk_live_*` vs `sk_live_*`), masked prefix, success/failure of a sample call, and the resolved API URL. **Run this first in any session.** |
|
|
102
|
-
| `get_openapi_spec` | Fetches the live `/v1/openapi.json` from
|
|
104
|
+
| `get_openapi_spec` | Fetches the live `/v1/openapi.json` from `SAAS_API_URL`. Reflects the deployed API exactly. |
|
|
103
105
|
| `list_end_users` | `GET /v1/auth/users` — paginated list of end-users in the tenant. Requires `sk_live_*`. |
|
|
104
|
-
| `list_oauth_providers` | Lists the OAuth providers (Google, …)
|
|
106
|
+
| `list_oauth_providers` | Lists the OAuth providers (Google, …) enabled for end-user social login. |
|
|
105
107
|
|
|
106
|
-
### Security & architecture
|
|
108
|
+
### Security & architecture (key-aware, no network calls)
|
|
107
109
|
|
|
108
|
-
| Tool |
|
|
110
|
+
| Tool | Does |
|
|
109
111
|
|---|---|
|
|
110
|
-
| `get_security_guide` |
|
|
111
|
-
| `recommend_stack` | Given an `app_type` (`frontend_only`, `fullstack`, `backend_service`, `mobile_app`, `cli_tool`, `desktop_app`) plus the detected key type, returns a framework recommendation that
|
|
112
|
+
| `get_security_guide` | Key-type-specific safe-usage cheat sheet. For `pk_live_*`: allowed endpoints and the "may be exposed in browser bundles" rule. For `sk_live_*`: leak vectors and the server-only architecture pattern. |
|
|
113
|
+
| `recommend_stack` | Given an `app_type` (`frontend_only`, `fullstack`, `backend_service`, `mobile_app`, `cli_tool`, `desktop_app`) plus the detected key type, returns a framework recommendation that physically prevents the key from leaking (Next.js App Router, Remix, SvelteKit, Nuxt, Astro for fullstack + secret; appropriate alternatives elsewhere). |
|
|
112
114
|
|
|
113
115
|
---
|
|
114
116
|
|
|
115
|
-
## Recommended call order
|
|
116
|
-
|
|
117
|
-
This is also what the startup banner of the server prints:
|
|
117
|
+
## Recommended call order
|
|
118
118
|
|
|
119
119
|
```
|
|
120
120
|
1. validate_credentials → confirm SAAS_API_KEY works, learn its type
|
|
@@ -126,39 +126,17 @@ This is also what the startup banner of the server prints:
|
|
|
126
126
|
7. get_sdk_template → start writing real code
|
|
127
127
|
```
|
|
128
128
|
|
|
129
|
-
For
|
|
129
|
+
For targeted questions ("how do I list organizations?"), `search_endpoints` + `get_endpoint_details` is faster than scrolling through `get_end_user_endpoints`.
|
|
130
130
|
|
|
131
131
|
---
|
|
132
132
|
|
|
133
|
-
##
|
|
134
|
-
|
|
135
|
-
```bash
|
|
136
|
-
cd mcp-server
|
|
137
|
-
npm install
|
|
138
|
-
npm run build # tsc → dist/
|
|
139
|
-
npm run dev # tsx, hot-reload
|
|
140
|
-
npm pack # build a local .tgz to test in your IDE before publishing
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
To point your IDE at a local build instead of npm:
|
|
133
|
+
## Support
|
|
144
134
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
"servers": {
|
|
148
|
-
"genlobe-local": {
|
|
149
|
-
"command": "node",
|
|
150
|
-
"args": ["/absolute/path/to/mcp-server/dist/index.js"],
|
|
151
|
-
"env": {
|
|
152
|
-
"SAAS_API_URL": "http://localhost:8001",
|
|
153
|
-
"SAAS_API_KEY": "pk_live_xxx"
|
|
154
|
-
}
|
|
155
|
-
}
|
|
156
|
-
}
|
|
157
|
-
}
|
|
158
|
-
```
|
|
135
|
+
- Sign up and manage API keys: [genlobe.ai](https://genlobe.ai)
|
|
136
|
+
- Issues and feature requests: [github.com/KleioTechnology/saas-multi-agent-tenant-ui/issues](https://github.com/KleioTechnology/saas-multi-agent-tenant-ui/issues) (this single tracker covers the whole Genlobe platform, including this MCP server)
|
|
159
137
|
|
|
160
138
|
---
|
|
161
139
|
|
|
162
140
|
## License
|
|
163
141
|
|
|
164
|
-
MIT
|
|
142
|
+
MIT.
|
package/dist/index.js
CHANGED
|
@@ -64,8 +64,13 @@ There are TWO types of authentication contexts:
|
|
|
64
64
|
- These endpoints ARE for building end-user frontends
|
|
65
65
|
|
|
66
66
|
## API Key Types
|
|
67
|
-
|
|
68
|
-
- \`
|
|
67
|
+
|
|
68
|
+
- \`pk_live_*\`: Public key — safe to expose in frontend code.
|
|
69
|
+
- **By itself** (no JWT) the key only unlocks \`/v1/auth/*\` (register, login, refresh, logout, me, forgot-password, reset-password). These are the seven scopes auto-assigned to public keys.
|
|
70
|
+
- **Combined with an end-user JWT** returned by \`/v1/auth/login\`, the same public key unlocks the full end-user API: \`/v1/user/agents/*\`, \`/v1/entity/records/*\`, \`/v1/plans\`, \`/v1/billing/*\`, \`/v1/users/me\`, etc. Once the JWT is in play, the JWT carries end-user identity and the public key just keeps verifying the tenant context.
|
|
71
|
+
- Restricted by an Origin allowlist (configured per key) and per-IP rate limits.
|
|
72
|
+
|
|
73
|
+
- \`sk_live_*\`: Secret key — backend-only, never expose. Required for server-to-server work that no end-user JWT can cover: defining entity schemas (\`/v1/entity/schemas/*\`), bulk record operations (\`/v1/entity/records/bulk\`, \`/v1/entity/records/search\`), webhooks, batch jobs, and other admin tooling on the tenant's own server.
|
|
69
74
|
|
|
70
75
|
## API Key Organization Scope (B2B2C)
|
|
71
76
|
|
|
@@ -102,6 +107,38 @@ If you're building a frontend application for end-users, you should:
|
|
|
102
107
|
2. Use the public API key (pk_live_*) for client-side requests
|
|
103
108
|
3. Include X-API-Key header in ALL requests
|
|
104
109
|
4. After login, also include Authorization: Bearer <jwt> for authenticated requests
|
|
110
|
+
|
|
111
|
+
## End-User App Flow (the canonical two-phase pattern)
|
|
112
|
+
|
|
113
|
+
A common confusion: the public key looks restricted to \`/v1/auth/*\`, so developers assume they need to ship the secret key in their frontend to call agents or records. They don't. The pattern is two phases:
|
|
114
|
+
|
|
115
|
+
\`\`\`
|
|
116
|
+
[Tenant's app frontend in the user's browser]
|
|
117
|
+
│
|
|
118
|
+
│ Phase 1 — auth gateway (public key alone is enough)
|
|
119
|
+
│ X-API-Key: pk_live_xxx
|
|
120
|
+
▼
|
|
121
|
+
POST /v1/auth/register ─┐
|
|
122
|
+
POST /v1/auth/login ├─ returns { access_token (JWT), refresh_token, user }
|
|
123
|
+
POST /v1/auth/refresh ─┘
|
|
124
|
+
│
|
|
125
|
+
│ Phase 2 — end-user features (public key + JWT)
|
|
126
|
+
│ X-API-Key: pk_live_xxx
|
|
127
|
+
│ Authorization: Bearer <end-user JWT>
|
|
128
|
+
▼
|
|
129
|
+
GET /v1/user/agents/available
|
|
130
|
+
POST /v1/user/agents/{id}/chat
|
|
131
|
+
GET/POST/PUT/DELETE /v1/entity/records/... ← custom-entity records as your app's DB
|
|
132
|
+
GET /v1/plans
|
|
133
|
+
POST /v1/billing/checkout
|
|
134
|
+
GET /v1/users/me
|
|
135
|
+
\`\`\`
|
|
136
|
+
|
|
137
|
+
The \`sk_live_*\` key never reaches the browser. It lives only on the tenant's own server, used for:
|
|
138
|
+
- defining entity schemas (\`/v1/entity/schemas/*\`),
|
|
139
|
+
- bulk record operations (\`/v1/entity/records/bulk\`, \`/search\`),
|
|
140
|
+
- receiving webhooks from the platform,
|
|
141
|
+
- cron jobs and admin tooling.
|
|
105
142
|
`,
|
|
106
143
|
base_url: API_URL,
|
|
107
144
|
documentation_urls: {
|
|
@@ -787,7 +824,7 @@ const END_USER_ENDPOINTS = {
|
|
|
787
824
|
]
|
|
788
825
|
},
|
|
789
826
|
billing: {
|
|
790
|
-
description: "Billing operations -
|
|
827
|
+
description: "Billing operations. Two flavors:\n\n- **Tier 1 (legacy / platform-level)**: endpoints under /v1/billing/* use the platform's Stripe and a SECRET key (sk_live_*) only. They were originally for Genlobe → Tenant billing and a since-superseded Tier 2 prototype; keep using them for tenant-internal flows.\n\n- **Tier 3 (Organization → end-user, Epic #209)**: each Organization runs its OWN Stripe (BYO key). End-users subscribe via /v1/organizations/{org_id}/billing/* (api key + JWT + active OrganizationMember). The Org's plan catalog is read via the public /v1/organizations/{org_id}/plans (api key only — no JWT). See the master spec at specs/features/billing/three-tier-billing.spec.md.",
|
|
791
828
|
endpoints: [
|
|
792
829
|
{
|
|
793
830
|
method: "GET",
|
|
@@ -880,6 +917,91 @@ const END_USER_ENDPOINTS = {
|
|
|
880
917
|
total_invoices: "number"
|
|
881
918
|
},
|
|
882
919
|
note: "Returns 404 if organization not found or doesn't belong to tenant."
|
|
920
|
+
},
|
|
921
|
+
// ---------------------------------------------------------------
|
|
922
|
+
// Tier 3 endpoints (Epic #209). Each Organization runs its OWN
|
|
923
|
+
// Stripe (BYO key). These run against the org's Stripe, not the
|
|
924
|
+
// platform's, and require an active OrganizationMember of the path's
|
|
925
|
+
// org. Plans are sold by the Organization to its end-users.
|
|
926
|
+
// ---------------------------------------------------------------
|
|
927
|
+
{
|
|
928
|
+
method: "GET",
|
|
929
|
+
path: "/v1/organizations/{organization_id}/plans",
|
|
930
|
+
summary: "List the Organization's active plans (Tier 3) — public to anonymous visitors of the org's app",
|
|
931
|
+
auth: { api_key: "pk_live_* or sk_live_*", jwt: false },
|
|
932
|
+
response: {
|
|
933
|
+
items: "array of OrganizationPlan: id (uuid), organization_id (uuid), name (string), slug (string), description (string | null), price_amount (decimal), currency (ISO-4217), billing_interval ('month' | 'year'), stripe_product_id (string | null), stripe_price_id (string | null), stripe_price_id_yearly (string | null), features (array of strings), limits (object<string, int | null>), is_active (boolean), created_at (ISO datetime), updated_at (ISO datetime)",
|
|
934
|
+
total: "number"
|
|
935
|
+
},
|
|
936
|
+
note: "Tenant-scoped: returns 404 if the Organization doesn't belong to the API key's tenant (no existence leak across tenants). Only plans with is_active=true and stripe_price_id != null are returned — use one of those plan ids when calling /billing/checkout-session.",
|
|
937
|
+
example_request: `GET /v1/organizations/660e8400-e29b-41d4-a716-446655440001/plans`
|
|
938
|
+
},
|
|
939
|
+
{
|
|
940
|
+
method: "POST",
|
|
941
|
+
path: "/v1/organizations/{organization_id}/billing/checkout-session",
|
|
942
|
+
summary: "Start a Stripe Checkout subscription flow for the calling end-user against an Org plan (Tier 3)",
|
|
943
|
+
auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
|
|
944
|
+
request_body: {
|
|
945
|
+
plan_id: "uuid (required) — OrganizationPlan id (NOT a Stripe price id). Get it from /v1/organizations/{organization_id}/plans.",
|
|
946
|
+
success_url: "string url (required) — Stripe redirects here on success.",
|
|
947
|
+
cancel_url: "string url (required) — Stripe redirects here if the user cancels."
|
|
948
|
+
},
|
|
949
|
+
response: {
|
|
950
|
+
checkout_url: "string — Stripe-hosted Checkout URL (redirect the user here).",
|
|
951
|
+
session_id: "string — Stripe Checkout session id (cs_*)."
|
|
952
|
+
},
|
|
953
|
+
errors: {
|
|
954
|
+
"403": "Caller is not an active OrganizationMember of the path's org.",
|
|
955
|
+
"404": "Plan not found / belongs to a different org / inactive (collapsed to the same 404 to avoid cross-org existence leaks).",
|
|
956
|
+
"409": "Plan has no stripe_price_id yet OR the Organization has no Stripe configured (the Org Owner must finish setup first)."
|
|
957
|
+
},
|
|
958
|
+
note: "The caller becomes the end-user customer in the Organization's Stripe account, not in the platform's. The actual Subscription row is created by the webhook handler after Stripe fires checkout.session.completed.",
|
|
959
|
+
example_request: `{
|
|
960
|
+
"plan_id": "770e8400-e29b-41d4-a716-446655440002",
|
|
961
|
+
"success_url": "https://claude.example.com/billing/success?cs={CHECKOUT_SESSION_ID}",
|
|
962
|
+
"cancel_url": "https://claude.example.com/pricing"
|
|
963
|
+
}`
|
|
964
|
+
},
|
|
965
|
+
{
|
|
966
|
+
method: "POST",
|
|
967
|
+
path: "/v1/organizations/{organization_id}/billing/customer-portal-session",
|
|
968
|
+
summary: "Open a Stripe Customer Portal session for the calling end-user (Tier 3, manage / cancel)",
|
|
969
|
+
auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
|
|
970
|
+
request_body: {
|
|
971
|
+
return_url: "string url (required) — Stripe redirects here when the user closes the Portal."
|
|
972
|
+
},
|
|
973
|
+
response: {
|
|
974
|
+
portal_url: "string — Stripe-hosted Customer Portal URL."
|
|
975
|
+
},
|
|
976
|
+
errors: {
|
|
977
|
+
"403": "Caller is not an active OrganizationMember of the path's org.",
|
|
978
|
+
"409": "Caller has no Subscription / no Stripe customer for this Organization yet, OR the Organization has no Stripe configured."
|
|
979
|
+
},
|
|
980
|
+
note: "Portal allowed actions (cancel / update payment method / etc.) are configured by the Organization Owner in their own Stripe Dashboard."
|
|
981
|
+
},
|
|
982
|
+
{
|
|
983
|
+
method: "GET",
|
|
984
|
+
path: "/v1/organizations/{organization_id}/billing/subscription",
|
|
985
|
+
summary: "Read the calling end-user's current subscription in this Organization (Tier 3)",
|
|
986
|
+
auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
|
|
987
|
+
response: {
|
|
988
|
+
id: "uuid",
|
|
989
|
+
organization_id: "uuid",
|
|
990
|
+
user_id: "uuid",
|
|
991
|
+
plan_id: "uuid | null",
|
|
992
|
+
status: "string | null — Stripe Subscription.status (active, past_due, canceled, …)",
|
|
993
|
+
billing_cycle: "string — 'monthly' or 'yearly'",
|
|
994
|
+
current_period_start: "ISO datetime | null",
|
|
995
|
+
current_period_end: "ISO datetime | null",
|
|
996
|
+
cancel_at_period_end: "boolean",
|
|
997
|
+
canceled_at: "ISO datetime | null",
|
|
998
|
+
trial_start: "ISO datetime | null",
|
|
999
|
+
trial_end: "ISO datetime | null"
|
|
1000
|
+
},
|
|
1001
|
+
errors: {
|
|
1002
|
+
"403": "Caller is not an active OrganizationMember of the path's org.",
|
|
1003
|
+
"404": "Caller has no Subscription for this Organization yet."
|
|
1004
|
+
}
|
|
883
1005
|
}
|
|
884
1006
|
]
|
|
885
1007
|
},
|
|
@@ -1026,6 +1148,29 @@ const END_USER_ENDPOINTS = {
|
|
|
1026
1148
|
error: "string | null"
|
|
1027
1149
|
},
|
|
1028
1150
|
note: "Returns 402 Payment Required if usage limits exceeded."
|
|
1151
|
+
},
|
|
1152
|
+
{
|
|
1153
|
+
method: "GET",
|
|
1154
|
+
path: "/v1/organizations/{organization_id}/usage",
|
|
1155
|
+
summary: "Get aggregate usage for one Organization in the queried period",
|
|
1156
|
+
auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
|
|
1157
|
+
query_params: {
|
|
1158
|
+
period_start: "ISO datetime (optional) - Inclusive start of the aggregation window (UTC). Defaults to the current calendar month.",
|
|
1159
|
+
period_end: "ISO datetime (optional) - Exclusive end of the aggregation window (UTC). Must be supplied together with period_start.",
|
|
1160
|
+
},
|
|
1161
|
+
response: {
|
|
1162
|
+
organization_id: "uuid",
|
|
1163
|
+
organization_name: "string | null - Human-readable name from organizations row, null if the org row was deleted",
|
|
1164
|
+
organization_slug: "string | null",
|
|
1165
|
+
period_start: "ISO datetime - resolved window start",
|
|
1166
|
+
period_end: "ISO datetime - resolved window end",
|
|
1167
|
+
messages_count: "number - Sum of messages_count across plan_usages rows for the org in the period",
|
|
1168
|
+
tokens_count: "number - Sum of tokens_count (input + output)",
|
|
1169
|
+
input_tokens_count: "number",
|
|
1170
|
+
output_tokens_count: "number",
|
|
1171
|
+
cost_usd: "string - Decimal as string (e.g. '12.345600')",
|
|
1172
|
+
},
|
|
1173
|
+
note: "Auth requires the caller to be an active OrganizationMember of the path's org. Returns a zero row when the org had no activity in the period, so callers can always render a header without a 404 fallback. Read-only — does not consume usage.",
|
|
1029
1174
|
}
|
|
1030
1175
|
]
|
|
1031
1176
|
},
|
package/package.json
CHANGED