docs: the Company (Agency/Corporate) API and MCP surface is undocumented

[salmov]

What is missing

The public docs have no coverage at all of the Company (Agency/Corporate) API and MCP surface. A search across docs/ and schema/ for api/v1/company, X-Publora-Workspace-Id or any agency wording returns zero hits.

Meanwhile the product ships an in-app reference on the Company API / MCP screen that documents the whole surface. Today that screen is the only place a customer can learn any of it, and an in-app panel is not something an integrator can link to, search, or read before they sign up.

Why it matters

An agency integrating Publora has no public answer to the first three questions they will ask:

• which base path to call,
• which headers identify the company and the client workspace,
• which calls require an Idempotency-Key, and what to do after a lost response.

Getting the last one wrong duplicates a customer's posts.

What needs documenting

Addressing

Base path	https://api.publora.com/api/v1/company
Every company call	X-Publora-Key: <the caller's personal API key>
Workspace-scoped calls	X-Publora-Workspace-Id: <the exact workspace id>
The media upload PUT	the reservation's own uploadHeaders only — never the Publora key

Start at GET /contexts/v2: the capabilities and commandVersion it returns are the authority the product's own UI obeys. A company refusal must never be retried through the personal API — it is an answer about permission, not a transport failure.

The callable surface, in the groups the product uses:

• Context: GET /contexts/v2, GET /accounts/:accountId/workspaces/:workspaceId/context, GET /platforms
• Workspaces: POST /accounts/:accountId/workspaces, .../rename, .../archive
• Team and access: GET /accounts/:accountId/team, GET .../workspaces/:workspaceId/members, POST .../invitations, POST /invitations/accept, .../resend, .../revoke, PUT .../memberships/:membershipId/workspace-grants/:workspaceId, POST .../offboard
• Channels: GET /connections, DELETE /connections/:connectionId, GET,POST,DELETE /connection-link, POST /connection-link/rotate, GET /connections/:connectionId/tiktok-creator-info
• Posts: GET /post-groups/page, /post-groups/summary, /calendar, GET,PATCH,DELETE /post-groups/:postGroupId, POST /post-groups, POST .../schedule, /reschedule, /unschedule, /recover
• Media: GET .../media, POST .../media/reservations, the uploadUrl PUT, POST .../media/:mediaFileId/complete, DELETE .../media/:mediaFileId
• Audit: GET /accounts/:accountId/audit-log

The MCP tools: company_context, company_workspaces, company_team, company_manage_team, company_channels, company_manage_channels, company_posts, company_save_post, company_post_action, company_media, company_audit_log.

Envelopes and errors. Answers keep the {success, data} envelope and {success: false, code, message} for domain errors; key-authentication failures keep the API's own {error} envelope. The code vocabulary should be listed, since a caller cannot branch on prose.

Idempotency. Idempotency-Key is required on every content mutation and on workspace create/rename/archive. After a lost response, retry with the identical body and the same key; a new intended operation takes a new key. Invitations and media delete are deliberately not keyed — say so, or integrators will key them anyway.

Acceptance criteria

• A guide covering addressing, the two headers, the envelopes and the idempotency rule.
• An endpoint page per group above, in the existing docs/endpoints/ style.
• The MCP tools in docs/mcp/tools-reference.md.
• schema/openapi.yaml carries the company paths.
• Mirrored into post-actor per the two-repo procedure, and the nav updated.

Out of scope

The product decisions themselves — this is documentation of a surface that already ships. No API change is being requested.

Raised from the Agency pilot (publora/publora.com#375) while reviewing the in-app Company API screen.