API QuickstartCopy Anchor Link

This guide walks through a complete integration — from your first API call to receiving webhook notifications. The current @gridwonk/sdk and @gridwonk/cli clients default to the canonical https://gridwonk.com API origin, so authenticated requests do not need a base URL override.

For utility application screening and package-bound human decisions, follow the utility lane guide. Those operations require the utility's own partner-scoped token; the management key used below is not a substitute for it.

That guide also covers package-bound notices. The SDK implements listUtilityNotices and getUtilityNotice for reads, plus separate create, update, named-transition, and send methods. Notice writes require current direct utility writer membership and partner.write; MCP exposes only reads. A successful send request is not proof of sent status or inbox delivery. These source bindings do not establish package publication, schema activation, or production release.

PrerequisitesCopy Anchor Link

• A GridWonk organization account
• A management API key (format: gw_live_... or gw_test_...).
• An HTTPS endpoint for webhooks (optional)

Document bytes never travel as JSON: packet intake issues a signed upload target and validates the stored object (files up to 30 MB; accepted formats and cohort-gated lanes are listed on the Partner Packets page) before it is accepted. The former base64 upload route (3 MiB) was retired on 2026-09-30 and returns 404.

Step 0: Bootstrap Your First Management Key (Invite-Only)Copy Anchor Link

For invite-only onboarding, bootstrap with a user session token:

curl https://gridwonk.com/api/v1/auth/bootstrap/status \
  -H "Authorization: Bearer $GRIDBOOST_SESSION_TOKEN"

If eligible (nextStep: "create_bootstrap_key"), create the first management key. A not_allowlisted status with nextStep: "contact_support" means the organization's API access or billing is suspended; no key can be minted until support restores access.

curl -X POST https://gridwonk.com/api/v1/auth/bootstrap-key \
  -H "Authorization: Bearer $GRIDBOOST_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"organizationId":"<org-id>","name":"Initial Management Key"}'

Use the returned key as GRIDBOOST_API_KEY for the remaining steps.

Step 1: Match a UtilityCopy Anchor Link

Find the canonical utility record for a given name:

curl -X POST https://gridwonk.com/api/v1/utilities/match \
  -H "Authorization: Bearer $GRIDBOOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Duke Energy Carolinas", "state": "NC"}'

Response:

{
  "match": {
    "eiaId": 5416,
    "name": "Duke Energy Carolinas",
    "confidence": 0.95
  },
  "utility": {
    "eiaId": 5416,
    "name": "Duke Energy Carolinas",
    "ownershipType": "Investor-Owned",
    "states": ["NC", "SC"],
    "rtoIso": "SERC"
  },
  "fromCache": false
}

Step 2: Upload Through Packet IntakeCopy Anchor Link

Uploading a document to a packet is a three-call flow on the partner packet API, documented on the Partner Packets page: create an intake for the packet (POST /api/v1/packets/intake), upload the file to the signed target the response selects (a signed upload for files up to 6 MB, resumable TUS above that), then finalize it (POST /api/v1/packets/intake/{intakeId}/finalize). Finalizing proves the uploaded object and starts the durable processing pipeline; GET /api/v1/packets/intake/{intakeId} reports acceptance, sanitization, text-recognition and searchable-PDF status. These calls need a partner-scoped token; a management key alone does not upload documents.

POST /api/v1/documents/digitize is the synchronous manual digitization endpoint for a document that already exists and is eligible for the legacy unmetered path. Trial and prepaid customer workspaces cannot use generic or legacy digitization to bypass supported packet processing. Do not call it after a normal intake; follow the intake status and supported recovery controls.

Asynchronous lifecycleCopy Anchor Link

Step 3: Monitor Job ProgressCopy Anchor Link

Option A: PollCopy Anchor Link

curl https://gridwonk.com/api/v1/jobs/a1b2c3d4-... \
  -H "Authorization: Bearer $GRIDBOOST_API_KEY"

Option B: Stream (SSE)Copy Anchor Link

curl -N https://gridwonk.com/api/v1/jobs/a1b2c3d4-.../stream \
  -H "Authorization: Bearer $GRIDBOOST_API_KEY"

Illustrative SSE events arrive as the job progresses:

event: job.update
data: {"id":"a1b2c3d4-...","status":"analyzing","progress":60,"step":"Digitizing document"}

event: job.complete
data: {"id":"a1b2c3d4-...","status":"complete","result":{...}}

The stream auto-closes after 55 seconds. Reconnect to continue watching.

The former single-document validation endpoint is retired and returns authenticated HTTP 410 Gone. Use packet intake Review instead.

Step 4: Query ResultsCopy Anchor Link

Query customer-released requirements for the utility:

curl "https://gridwonk.com/api/v1/published-requirements?utility=nashville-electric-service&state=TN" \
  -H "Authorization: Bearer $GRIDBOOST_API_KEY"

Coverage is everything published except utility-rejected rows, with honest gaps. Rows still awaiting a current utility decision come back marked reviewStatus: "pending" rather than being withheld — rows awaiting reviewed wording are separately withheld and counted in filteredOutCount. Read message and summary rather than inferring "no requirements" from an empty array. See Requirements API.

The older GET /api/v1/requirements read is a permanent tombstone. Authenticated calls return typed 410 Gone / ENDPOINT_GONE with /api/v1/published-requirements as the replacement.

Or query deficiency findings:

curl "https://gridwonk.com/api/v1/deficiency-reports?utility=duke-energy&severity=critical&findingState=open" \
  -H "Authorization: Bearer $GRIDBOOST_API_KEY"

Step 5: Set Up Persistent WebhooksCopy Anchor Link

For ongoing event notifications, create a webhook subscription:

curl -X POST https://gridwonk.com/api/v1/webhooks \
  -H "Authorization: Bearer $GRIDBOOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/hooks/gridwonk",
    "events": ["job.completed", "job.failed", "document.digitized"]
  }'

Save the secret from the response — you'll need it to verify webhook signatures. See the Webhook Integration Guide for full details.

Step 6: Check UsageCopy Anchor Link

Monitor your API consumption:

curl "https://gridwonk.com/api/v1/usage?days=7" \
  -H "Authorization: Bearer $GRIDBOOST_API_KEY"

Next StepsCopy Anchor Link

• Authentication & Rate Limiting — key management, rate limits, security
• External API endpoint index — full endpoint reference
• Webhook Integration Guide — event types, payloads, verification
• MCP API — JSON-RPC tool access for AI agents

Salesforce SDK scopeCopy Anchor Link

GridWonkClient now implements searchSalesforceApplications, getSalesforcePacketManifest, importSalesforcePacket, and getSalesforceImport for an approved connector. The connector is still default-disabled and the updated SDK has not been published. Use the required scoped credential; acknowledge: true and a stable idempotencyKey are mandatory for import. The client does not automatically retry that POST. See Salesforce setup.