docs: document the Context Management API in the API and MCP guides

[chenxin-yan]

Summary

The Context Management API (24 operations over HTTP and MCP) is live, and its generated reference pages are already published. The hand-written guides around them hadn't caught up yet:

• OpenAPI overview
  • Permissions: removed project:context:read, which no public endpoint checks, and listed org:context:read and org:context:write. Also states that Context Management needs an Organization key, since project keys can't hold these permissions.
  • Targeting: Context Group routes (/v2/context-groups/{groupId}) use the Organization that owns the group.
  • Rate limits: "Medium" now says context generation, and Context Management is listed under the default limit (200/min).
  • Pagination: new section covering { items, nextCursor }, limit (1–100, default 50), cursor, and how cursors are tied to the list that issued them.
  • Status codes: 409 now covers Glossary term and Custom Prompt rename conflicts, and 413 mentions the 1 MiB Context Management response limit.
• For coding agents: the MCP section describes the Context Management tools. It also says they need Context permissions on an Organization key or sign-in, and that they target orgId or groupId.
• API keys: says what the Organization Context permission is for, and that project keys can't manage Context Groups.
• API reference: the capability list now includes Context Management, project and key creation, runtime translation, and context generation.
• Defining context for translations: adds a developer note that points to the API and MCP tools for automating Context Group changes.

Evidence

I checked every claim against gt-cloud main before writing it:

• Permissions: operations/context/** authorization; packages/node/src/auth/apiKeyPermissions.ts (project keys can't grant org:*); project:context:read isn't referenced in apps/api/src.
• Targeting: contextGroupAuthorization resolves the Organization from groupId.
• Rate limits: context-management has no explicit limit, so it gets the 200/min default; context generation uses mediumRequestLimit.
• Pagination: packages/settings/src/pagination.ts and defineListOperation cursor binding.
• 409: returned by POST /v2/orgs/{orgId}/projects, POST /v2/project/branches/create, and the glossary and custom-prompt PATCH routes in openapi.public.json.
• 413: the response size limit in operations/context/management.ts.
• Validators: validate-links, validate:unsafe-html, validate:callouts, validate:reference-links and validate:structure all pass.

Following the AGENTS.md authentication boundary, HTTP prose mentions only API keys. Sign-in is mentioned only in the MCP section, where OAuth sign-in is a customer workflow.

Merge Danger

Door: two-way. Prose-only changes to five hand-written pages; nothing generated is touched.

Blast radius: docs only.

[cursor]

Risk: low. Approved. This is a small, reversible docs-only update to existing API and MCP guide pages with no automated-review findings that need human review.

  

_{Sent by Cursor Approval Agent: Pull Request Router}