Integrations Overview

Public plugin availabilityCopy Anchor Link

When the public rollout is enabled, install the GridWonk plugin, sign in, and confirm one workspace in your browser. It exposes a curated customer catalog separate from existing organization integrations. Human decisions, membership changes, and purchases remain website workflows. Its transport is stateless: the server checks the exact OAuth session on every request, while the tool list stays stable before and after activation.

Trial and prepaid workspaces use supported packet intake and reviews within their processing allowances. The broader integration capabilities below do not enable native DWG processing, legacy digitization, generic jobs, or unrestricted chat for those workspaces.

GridWonk is built from the ground up to be used by AI agents and integrated into other platforms.

How To Read ExamplesCopy Anchor Link

An example explicitly labeled runnable can be executed after you set its named credentials and replace any angle-bracket placeholders. Response bodies, event transcripts, command synopses, and snippets not labeled runnable are illustrative: they explain the contract but are not complete programs.

Integration MethodsCopy Anchor Link

API AccessCopy Anchor Link

Direct REST API access with raw organization API-key or OAuth JWT Bearer authentication and SSE streaming responses. The complete authenticated partner OpenAPI document covers every machine-credential operation (its remediation working-draft and export routes are documented as always-on since 2026-08-26). Its only omissions are the two session-only bootstrap routes and the authenticated route that serves the OpenAPI document itself. See the API Reference.

Partner-scoped REST also includes DWG companion intake. Standalone CAD creation has no matching SDK, CLI, or MCP binding; use the documented /api/v1/packets/cad-intake routes directly. Batch reserve, status, heartbeat, pairing, item cancellation, and abandonment have all four bindings. CAD declarations and pairing remain applicant-only; ordinary document batches also support utility-owned drafts. ZIP create/status/finalize/abandon and individual document cancel/reauthorize/retry-processing also have REST, SDK, CLI, and MCP bindings. Utility ZIPs accept PDF, PNG and JPEG, and recovery retains the original archive or intake identity. See Partner Packets.

File Library attachment and exact-document review use the same packet identity and authorization checks across REST, SDK, CLI, hosted MCP, and local MCP. Document deletion is deliberately absent from MCP; use the confirmed CLI command or REST/SDK binding while the packet is editable. The cohort is a server-side applicant-organization allowlist and is not tied to NES. Utilities gain automated drawing checks independently through reviewed CAD procedure profiles, so the same intake contract can serve more utilities without duplicating routes.

The utility lane also exposes manual package freeze, finding adjudication, screening completion, and study requirements through REST, SDK, and confirmed CLI commands. These human decisions are excluded from MCP and the agent-facing OpenAPI projection. MCP may start authorized utility screening; it cannot make the utility's decision. Notice REST/SDK/CLI operations are now implemented, with current direct utility membership, named transitions, strict fields, and on-file recipients for send. MCP and the curated OpenAPI projection expose notice list/detail reads only. Delivery progress is separate from canonical sent status and inbox delivery. The dependent utility-event layer extends existing webhook subscriptions without giving a subscriber decision or send authority; schema activation, package publication, and production release remain separate gates.

The app host builds a smaller curated OpenAPI document for /openapi.json and /.well-known/openapi.json. Anonymous publication is off, so both routes return 404 today. It contains the OAuth token exchange and only active partner packet operations that also have hosted MCP bindings. Each operation has a stable function-safe identifier, a named schema for every status it can return, and an exact partner.read or partner.write requirement. Its wording is written for partners rather than copied from the operator document, so it omits internal rollout gates, quota figures, and processing vendors — fetch the complete document when you need those. The public developer guide and root /llms.txt explain when to use REST, MCP, CLI, or the human web workflow.

Public integration requests are bounded before parsing. Oversized JSON, form, webhook, agent, or PDF payloads are rejected with safe client errors, and internal agent details are not echoed to external callers. PDF clients may send wrapped or URL-safe base64; the upload boundary normalizes it before validation.

Session CLI AccessCopy Anchor Link

Session-backed CLI access for user and admin workflows. This is the path for Claude Code, Codex, and similar coding agents that need full platform parity beyond the external API.

MCP Server DiscoveryCopy Anchor Link

Machine-readable catalog of GridWonk's MCP tools at /.well-known/mcp.json. Fetching this catalog requires a docs session — it names every tool GridWonk exposes, so it is not served anonymously.

At runtime, the gateway filters that catalog by credential. Organization API keys and scope-less tokens see broad tools; partner.read / partner.write OAuth tokens see only packet tools granted by those scopes. The same policy guards direct tool calls, so discovery cannot overstate authority. Standard OAuth metadata at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource describes the live client-credentials flow and exact public MCP resource audience. Separately gated user-OAuth lanes add account sign-in with PKCE only after their own approved registration and activation. The admin MCP endpoint remains a separate operator lane: machine client-credentials tokens do not authorize it. Its user-OAuth lane requires its own client/audience and current administrator authority. Confirmed remote mutation pairs also require the separate remote mutation gate; that gate does not disable administrator read operations.

Neither hosted MCP surface currently offers a standalone server-initiated event stream. An event-stream GET receives 405 even when the media type uses mixed letter case; normal JSON discovery GETs remain available. MCP clients should treat 405 as final rather than reconnecting.

To connect Claude Code or OpenAI Codex, follow the Claude Code and Codex Setup guide. It provides separate least-privilege paths for external users and authorized internal operators.

Developer project list, read, create, and editable-draft update operations share one tenant-scoped service across REST, SDK, CLI, and the broad MCP catalog. They use organization-key authority; fine-grained project OAuth scopes are not live.

Requirement lookup is consistent across REST, SDK, CLI, and MCP integrations. The current lane (/api/v1/published-requirements, queryPublishedRequirements(), gridwonk requirements published, query_published_requirements) serves rows through one reader: every published row except the ones a utility reviewer explicitly rejected, with each row marked reviewStatus: "approved" or reviewStatus: "pending". All four bindings return the same typed releaseStatus (released, partially_released, review_incomplete, or not_published), which reports utility-review progress rather than gating what is served, so unknown utilities and uncovered categories remain explicit rather than becoming a near miss. The legacy SDK, CLI, and MCP bindings have been removed. The old authenticated REST URL remains only as a permanent 410 Gone notice that names /api/v1/published-requirements as its replacement. See Requirements API.

The root /llms.txt endpoint is a public marketing-content index and operating guide for AI agents. It inlines every public marketing page, including the Developers page, and links the developer guide, anonymous curated OpenAPI document, authenticated MCP endpoint, contact route, sitemap, and robots file. /llms.txt does not expose the protected docs corpus or the complete authenticated capability map.

The negotiated Markdown twin for the public Developers page links directly to /openapi.json, so an agent requesting Markdown can move from the integration overview to the curated machine contract without guessing a discovery URL.

Those public pages do not mount the account-settings or URL-state providers used by the authenticated dashboard. Their server-rendered HTML keeps the integration explanation and discovery links available to readers that do not run client-side JavaScript.

WebhooksCopy Anchor Link

Event-driven notifications when jobs complete, jobs fail, or documents are digitized. The retired legacy requirements read no longer emits events, and published-requirements reads emit none. The legacy deficiency.found and screening.complete names remain reserved unless they appear inside a job completion payload.

Five separate utility.* families describe actual human screening determinations, finding decisions, study requirements, package freezes, and canonical notice changes. They commit with the business change, preserve originating identity, and deliver in application order for each receiving-utility subscription. They require the separately approved utility-event release and do not backfill history. See Webhook Integration Guide.

Salesforce: implemented, not activatedCopy Anchor Link

The Salesforce utility connector implements source snapshots, four authenticated REST/MCP/SDK operations, current permission across captured history, and durable service-owned package freezing. It remains disabled pending sandbox acceptance and separate activation approval. Existing utility packet review commands do not enable Salesforce imports or delivery; the immutable package makes no queue/status, decision, or notice changes.

AuthenticationCopy Anchor Link

Most external runtime integrations can use an organization API key directly or exchange that key for a short-lived OAuth bearer JWT. This runnable API-key request uses the direct form:

curl -X GET https://gridwonk.com/api/v1/jobs \
  -H "Authorization: Bearer gw_live_..."

Legacy gb_live_/gb_test_ keys are no longer accepted. Use a gw_live_... or gw_test_... key.

API keys and the OAuth tokens issued from them are organization-bound and enforce tenant isolation. Session-only bootstrap/OpenAPI routes and the client-credentials token exchange have separate authentication rules. A platform-admin suspension of an organization's API and MCP access, or an account billing suspension, refuses every API-key and MCP request with 403 FORBIDDEN (api_access_suspended or billing_suspended). See Authentication & Rate Limiting for the full lane matrix, key management, rate limits, and security best practices.

Use the credential lane documented by each integration. Internal workflow and docs-service calls use WORKFLOW_INTERNAL_TOKEN; scheduled-job CRON_SECRET values are not interchangeable with that service credential.

Management keys own key lifecycle operations. Runtime keys can call allowed API endpoints but cannot create, update, or revoke keys.

For CLI parity workflows, use a GridWonk user session token:

export GRIDBOOST_SESSION_TOKEN=sb_...
gridwonk auth connect --client codex
gridwonk capabilities --json
gridwonk orgs list --json

Machine-Readable EndpointsCopy Anchor Link

The host matters: docs-host /.well-known/openapi.json and /.well-known/mcp.json routes sit behind the docs session, as do full docs search, raw docs reads, and protected docs pages. The app-host OpenAPI routes carry the curated projection and are currently unpublished, returning 404. Search and raw reads apply the active organization's effective audience, so customer and impersonated sessions cannot read internal pages. Every API or MCP operation described by public metadata still requires its documented Bearer credential.