docs: Programmatic & Agentic Access guide + Organizations API reference (#2453, #2454)

[aaitor]

What

Two Organizations docs sub-issues, bundled per request:

#2453 — Programmatic & Agentic Access guide

New solutions/organizations/programmatic-access.mdx: the org-management surface is fully API-driven with an admin key (no browser-only actions), plus the three public agent-discovery endpoints (llms.txt, agentic-instructions.md, ai-catalog.json ARD catalog). Wired into nav + overview.

#2454 — Organizations API reference (API tab)

• New docs/api-reference/organizations-openapi.json — 63 operations, generated from the merged /api/v1/organizations/docs-json endpoint (nvm #2457): org tags only, @WebappOnly and ops-token endpoints (create-org, bootstrap x2, invitation sweep) excluded.
• Wired into the API tab as an auto-generating Organizations group (openapi.source) — Mintlify renders one page per operation, grouped by tag.

Verification

• mintlify dev loads the org spec + auto-generates the group — no OpenAPI validation errors.
• mintlify broken-links clean; docs.json valid. Spec made OpenAPI 3.0-valid (stripped a schema-level examples array; media-type example kept).

eruizgar91 had approved the #2453-only version; the #2454 addition dismissed that approval on push, so the API-tab section needs a fresh review. Follow-up (nvm #2455): finer per-controller org tags to split the large Organizations group into sub-sections.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Nevermined	🟢 Ready	View Preview	Jul 27, 2026, 2:53 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[Copilot]

Pull request overview

Adds an Organizations documentation page that explains how to manage organizations headlessly via an admin API key, and how autonomous agents can discover an organization’s public agent-discovery endpoints.

Changes:

• Added a new “Programmatic & Agentic Access” guide covering admin-key auth, automation entry points, and public discovery endpoints.
• Linked the new guide from the Organizations overview page.
• Wired the new page into the Mintlify navigation.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
docs/solutions/organizations/programmatic-access.mdx	New guide describing programmatic org management and public discovery endpoints.
docs/solutions/organizations/overview.mdx	Adds a feature card linking to the new guide.
docs.json	Adds the new guide to the Organizations section navigation.

Comments suppressed due to low confidence (1)

docs/solutions/organizations/programmatic-access.mdx:62

• “One call provisions a customer account … and hands back a scoped key” is not always true if onboarding hits the consent-required path (existing account you don’t own), which requires an approval + retry. Consider qualifying this so automation callers aren’t surprised by the two-step case.

  The [White-label Onboarding](/docs/solutions/organizations/white-label-onboarding) flow is purpose-built for automation: one call provisions a customer account under your brand and hands back a scoped key to pay for your agents on their behalf.

[eruizgar91]

Overview

Adds one new page (docs/solutions/organizations/programmatic-access.mdx), wires it into docs.json nav after Activity & Events, and adds a feature card on the Organizations overview. Docs-only and additive.

Verified on my side: all 8 internal links resolve to files that exist on the head branch, the nav entry is valid and well-placed, the auth wording matches workspaces-and-members.mdx:95, and the "Premium and Enterprise" gating claim is consistent with the tier table in plans-and-billing.mdx. Nothing is broken — approving. The notes below are improvements, not blockers.

Also agree with deferring #2454: half a spec-bound reference would be worse than none.

Suggestions

1. No Python tab. CLAUDE.md requires TypeScript and Python where applicable, and the sibling page docs/integrate/patterns/organizations.mdx:54 does exactly that (get_my_memberships()). This page ships cURL + TypeScript only.

2. The TypeScript tab doesn't demonstrate what the section is about. It's a bare Payments.getInstance() with a comment, while the cURL tab calls my-memberships. Making the tabs parallel would help:

const memberships = await payments.organizations.getMyMemberships()

3. "admin API key" reads as a key type that doesn't exist. Per workspaces-and-members.mdx, Admin is a member role and keys are owned by the organization. Readers may go looking for a special key type. Suggest: "an API key belonging to a member with the Admin role in that organization."

4. The auth prose contradicts its own example. The text says the header is for when the key isn't org-scoped ("otherwise target a workspace explicitly"), then the cURL sends both. And per the documented priority order in integrate/patterns/organizations.mdx:18 (route param → header → key's org tag), the header actually wins over the key scope — so "that scope applies automatically" is slightly misleading. Either drop the header from the example, or state that the header overrides the key's scope.

5. Placeholder org ID. org-abc123 vs. the realistic org-9d81acea-7d38-460e-b7c0-c3b92abcbb07 already used in getting-started/ai-agent-purchase.mdx:40. Matching it also makes the cURL copy-pasteable against sandbox.

6. Worth a line on admin-key handling. The page recommends driving an org headlessly with an admin key and, two paragraphs later, lists "fund groups, and withdraw" among what that key can do — handing it to an autonomous agent is a treasury-drain path. One sentence would cover it: an admin key can invite members, move treasury funds, and withdraw, so keep it server-side and never ship it to an agent or client you don't control. This is the one I'd most like to see added.

Smaller notes

• Cross-link the existing coverage. llms.txt / agentic-instructions.md are already documented in solutions/api-providers.mdx:368 and getting-started/ai-agent-purchase.mdx:40 (the latter has a working end-to-end demo). Linking this page → ai-agent-purchase, and ideally a pointer from api-providers.mdx back here, avoids having three pages describe the same endpoints with no path between them.
• ai-catalog.json isn't in the tier table. plans-and-billing.mdx:25 lists Premium as "AI instructions + llms.txt". If the ARD catalog is a Premium feature, adding it there keeps the two pages in agreement.
• "Full API reference" section creates a TOC anchor that leads only to a "coming soon" note. Folding the note into the preceding section (or linking the tracking issue) would stop the sidebar advertising an empty section.

Risk

Low. Additive docs, no generated-file boundaries crossed (api-reference/ untouched), no code. The only claims I can't verify from this repo are the endpoint behaviors themselves (404 for non-Premium, metadata carrying x402 terms); the PR body says these were checked against organizations-integration.controller.ts, and they're consistent with what's already documented here.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Nevermined	🟡 Building	–	Jul 27, 2026, 2:51 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[aaitor]

Thanks @eruizgar91 — all addressed in 1c10585:

1. Python tab — added, with get_my_memberships() (mirrors integrate/patterns/organizations.mdx).
2. Parallel TS example — the TS tab now calls payments.organizations.getMyMemberships() instead of a bare init.
3. "admin key type" — reworded to "a Nevermined API key that belongs to a member with the Admin role."
4. Auth prose vs. example — now states the X-Current-Org-Id header overrides the key's own scope (matching the documented priority order).
5. Realistic org-id — swapped org-abc123 → org-9d81acea-… (matches ai-agent-purchase.mdx).
6. Admin-key handling — added a <Warning>: an admin key can invite members, move treasury funds and withdraw, so keep it server-side and never ship it to an agent/client you don't control.

Smaller notes: cross-linked Buy & Call a Paid Agent (the working demo); added the ARD catalog to the Premium tier row in plans-and-billing.mdx; and the "Full API reference" section is no longer a coming-soon stub — it now points at the #2454 Organizations API group added to this PR.

Copilot's "no browser-only actions" note is handled too. Ready for a fresh look — note this PR now also carries the #2454 API reference (the auto-generated Organizations group in the API tab).

[eruizgar91]

Review — Programmatic & Agentic Access + Organizations API reference

Reviewed the API-tab addition (which dismissed the earlier approval) plus the guide. Approving — everything below is non-blocking, but #1 is worth landing here as a one-line CLAUDE.md entry.

Verified

• Spec integrity — 63 paths / 80 operations, no duplicate operationIds, every operation has a summary, all $refs resolve, no schema-level examples arrays and no type: "null" left, so it is genuinely OpenAPI 3.0-valid. Zero path overlap with the existing openapi.json, so no duplicate pages in the API tab.
• Doc claims match the spec — the three discovery endpoints are unauthenticated (security: null) with exactly the media types the table states (text/plain, text/markdown, application/json), and each documents a 404, matching the "Premium/Enterprise only" sentence. The X-Current-Org-Id precedence description is consistent with integrate/patterns/organizations.mdx.
• Links — every href in the new page resolves on this branch (groups-and-budgets, wallets, white-label-onboarding, ai-agent-purchase).
• Leakage — no staging_* env names, internal hosts, or credential-shaped example values in the spec; only *@example.com and a dummy 0x… address.
• Conventions — frontmatter complete, TypeScript + Python tabs, sandbox only, and the admin-key <Warning> is exactly the right call-out.

Findings

1. The generated spec has no sync path, so the manual fix will be lost (medium)

The description notes that a schema-level examples array was stripped by hand to make the spec 3.0-valid, but nothing records that: no workflow, no entry in the "Generated files — never edit by hand" list in CLAUDE.md, no generation command in the file. The next regeneration silently reintroduces the invalid construct, or someone hand-edits the file assuming it is authored here. Either add it to that list with its source endpoint (/api/v1/organizations/docs-json), or mirror the sync-errors-docs.yml pattern — and ideally fix the examples shape at the source so no post-processing is needed.

2. X-Current-Org-Id is documented but declared on 0/80 operations (medium)

The guide leads with the header, but no operation lists it as a parameter, so the API-tab playground cannot send it. This matters for the four paths with no {orgId}: PUT /organizations, GET /organizations/my-memberships, POST /organizations/members, GET /organizations/user-info/{userId} — a reader of PUT /organizations has no way to tell which organization they are mutating. Source-side @ApiHeader fix; good candidate for the nvm #2455 follow-up.

3. "Full API reference" section links to nothing (low)

docs/solutions/organizations/programmatic-access.mdx:107 describes the Organizations group in prose while every other section on the page links out. Point it at the API tab or at one generated page.

4. API-key link target (low)

docs/solutions/organizations/programmatic-access.mdx:11 — "Nevermined API key". That page explains key scoping, not how to obtain a key. Suggest linking the key itself to /docs/getting-started/get-your-api-key and keeping the scoping link on the following sentence.

5. Cosmetic drift vs the main spec (low)

The new spec is 3.0.0 with security scheme Authorization; openapi.json is 3.1.0 with bearerAuth. Server descriptions also differ ("Sandbox" vs "Sandbox (Testing) - Base Sepolia"), so the two API sections display different environment labels. Harmless functionally, but visible to readers.

6. Operation count (trivial)

The description says "63 operations"; 63 is the path count — the spec has 80 operations.