feat(agents): read and create agents; device-code status takes the code in the body by kphurley7 · Pull Request #1179 · lightsparkdev/grid-api

kphurley7 · 2026-10-14T08:42:17Z

Agent read and create, and device-code status without the code in the URL.

GET /agents/{agentId} and POST /agents document a 403 when the Agents API is not enabled for the platform; POST /agents documents a 404 for an unknown customer.
Breaking: device-code status moves from GET /agents/device-codes/{code}/status to POST /agents/device-codes/status with the code in the body, so the secret stays out of URLs and access logs. The response gains a status enum.
The device code is documented as an opaque 128-bit value; regenerating invalidates the one unredeemed code.
Policy amounts are documented as denominated in the immutable spending-limits currency.
Stainless maps the moved status route.

Needs the breaking-change label and API-reviewer approval.

…de in the body GET /agents/{agentId} and POST /agents answer 403 when the Agents API is not enabled for the platform, and POST /agents answers 404 for an unknown customer. The device-code status check moves from GET /agents/device-codes/{code}/status to POST /agents/device-codes/status with the code in the body, so the secret never appears in a URL or access log (breaking for that path). The status response gains a status enum, the device code is documented as an opaque 128-bit value, and regenerating invalidates the one unredeemed code. Policy amounts are documented as denominated in the policy's immutable spending-limits currency. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TeBuC5ym3AR1ZJ6eocSFGT

mintlify · 2026-10-14T08:42:21Z

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

Project	Status	Preview	Updated
Grid	🟢 Ready	View Preview	Oct 14, 2026, 8:43 AM

vercel · 2026-10-14T08:42:24Z

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments

Project	Deployment	Actions	Updated
grid-cards-demo	Ignored	Preview	Oct 14, 2026 5:35pm UTC
grid-flow-builder	Ignored	Preview	Oct 14, 2026 5:35pm UTC
grid-wallet-demo	Ignored	Preview	Oct 14, 2026 5:35pm UTC

github-actions · 2026-10-14T08:42:37Z

⚠️ Breaking OpenAPI changes detected

oasdiff reports 1 error / 0 warning changes to openapi.yaml.
This PR will need approval from an API reviewer before merge.

Errors (1)

GET /agents/device-codes/{code}/status — api path removed without deprecation [api-path-removed-without-deprecation].

Detected by oasdiff. Full report: job summary or the oasdiff-report artifact.

greptile-apps · 2026-10-14T17:19:35Z

Confidence Score: 4/5

[Critical impact] Changes the public API contract for device code status endpoint.

The PR appears safe to merge with the dependent currency fix in PR #1180; the stale polling reference is a non-blocking documentation issue.

Findings

Polling guide uses removed route ▶

Fix with agent prompt

### Issue 1
openapi/openapi.yaml:351-352
The route moved, but `.claude/skills/grid-api/references/endpoints.md:270` still lists `GET /agents/device-codes/{code}/status`. The API skill recommends this reference for API questions, so users now get the wrong method and path for polling. Update that row to `POST /agents/device-codes/status` and explain the required JSON `code` body. PRs #1180–#1186 also leave this reference unchanged.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

This PR updates agent read and create errors and moves device-code polling to POST /agents/device-codes/status.

Device-code status checks send the code in the body and return its state.
Agent management docs name disabled-platform and missing-customer replies.
Device codes have a fixed format, lifetime, and one-active-code rule.
Policy amounts use the spending-limits currency.
Agent-operated endpoints are now marked experimental.

Diagram

sequenceDiagram
  participant Platform
  participant Grid
  Platform->>Grid: POST /agents
  Grid-->>Platform: Agent and device code
  Platform->>Grid: POST /agents/device-codes/status with code
  Grid-->>Platform: code, status, redeemed
  Note over Platform,Grid: Platform calls keep BasicAuth

_{Reviews (1) · Last reviewed commit: "feat(agents): read and create agents; de..." · Reviewed by Greptile}

greptile-apps · 2026-10-14T17:19:38Z

+  /agents/device-codes/status:
+    $ref: paths/agents/agents_device-codes_status.yaml


Polling guide uses removed route

The route moved, but .claude/skills/grid-api/references/endpoints.md:270 still lists GET /agents/device-codes/{code}/status. The API skill recommends this reference for API questions, so users now get the wrong method and path for polling. Update that row to POST /agents/device-codes/status and explain the required JSON code body. PRs #1180–#1186 also leave this reference unchanged.

Knowledge Base Used: Grid API contract

Prompt To Fix With AI

This is a comment left during a code review. Path: openapi/openapi.yaml Line: 351-352 Comment: **Polling guide uses removed route** The route moved, but `.claude/skills/grid-api/references/endpoints.md:270` still lists `GET /agents/device-codes/{code}/status`. The API skill recommends this reference for API questions, so users now get the wrong method and path for polling. Update that row to `POST /agents/device-codes/status` and explain the required JSON `code` body. PRs #1180–#1186 also leave this reference unchanged. **Knowledge Base Used:** [Grid API contract](https://app.greptile.com/lightspark/-/custom-context/knowledge-base/lightsparkdev/grid-api/-/docs/api-contract.md) --- For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Fixed: the reference now lists POST /agents/device-codes/status with the code in the body; redeem is updated the same way in #1180.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TeBuC5ym3AR1ZJ6eocSFGT

k15z · 2026-10-14T17:37:18Z

-    $ref: paths/agents/agents_device-codes_{code}_status.yaml
+  /agents/device-codes/status:
+    $ref: paths/agents/agents_device-codes_status.yaml
  /agents/device-codes/{code}/redeem:


redeem still has the code in the path here

k15z · 2026-10-14T17:37:18Z

+    example: jqzJR3AgI9OAwb_enypARw
+  status:
+    $ref: ./AgentDeviceCodeStatus.yaml
  redeemed:


with status in here, redeemed is just status == REDEEMED, and code just echoes back what we sent. since we're already breaking this route anyway, worth dropping one or both? not blocking

ls-bolt · 2026-10-14T17:37:51Z

🦣 Congratulations @k15z - your substantive review earned a Straight-tusked elephant! (rare)

A huge warm-climate elephant, it ranged across Europe and western Asia between glacial advances.

View your Frost-dex: https://zeus.dev.dev.sparkinfra.net/#/dinodex/k15z?section=ice-age

github-actions Bot added the breaking-change Introduces a breaking change to the OpenAPI spec label Oct 14, 2026

mintlify Bot deployed to staging - mintlify October 14, 2026 08:43

View deployment

kphurley7 requested a review from k15z October 14, 2026 17:14

kphurley7 marked this pull request as ready for review October 14, 2026 17:14

greptile-apps Bot reviewed Oct 14, 2026

View reviewed changes

docs(agents): reference lists the body-based device-code status route

f66177f

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TeBuC5ym3AR1ZJ6eocSFGT

k15z reviewed Oct 14, 2026

View reviewed changes

k15z approved these changes Oct 14, 2026

View reviewed changes

kphurley7 merged commit fdd9202 into main Oct 14, 2026
10 checks passed

kphurley7 deleted the kph/muse-spec-a-agent-read-create branch October 14, 2026 17:50

Navigation Menu

Repository navigation

feat(agents): read and create agents; device-code status takes the code in the body - #1179

feat(agents): read and create agents; device-code status takes the code in the body#1179
kphurley7 merged 2 commits into
mainfrom
kph/muse-spec-a-agent-read-create

kphurley7 commented Oct 14, 2026

Uh oh!

mintlify Bot commented Oct 14, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Oct 14, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 14, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot commented Oct 14, 2026 •

edited

Loading

Diagram

Uh oh!

greptile-apps Bot Oct 14, 2026

Uh oh!

kphurley7 Oct 14, 2026

Uh oh!

k15z Oct 14, 2026

Uh oh!

k15z Oct 14, 2026

Uh oh!

ls-bolt Bot commented Oct 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		/agents/device-codes/status:
		$ref: paths/agents/agents_device-codes_status.yaml

Conversation

kphurley7 commented Oct 14, 2026

Uh oh!

mintlify Bot commented Oct 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel Bot commented Oct 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ Breaking OpenAPI changes detected

Errors (1)

Uh oh!

greptile-apps Bot commented Oct 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 4/5

Findings

Summary

Diagram

Uh oh!

greptile-apps Bot Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

kphurley7 Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

k15z Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

k15z Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

ls-bolt Bot commented Oct 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mintlify Bot commented Oct 14, 2026 •

edited

Loading

vercel Bot commented Oct 14, 2026 •

edited

Loading

github-actions Bot commented Oct 14, 2026 •

edited

Loading

greptile-apps Bot commented Oct 14, 2026 •

edited

Loading