docs: Agent Signup & Verify endpoints#104
Merged
Merged
Conversation
Add two new unauthenticated endpoints for programmatic agent onboarding: - POST /api/agents/signup — register with email, instant key for agent+ prefix - POST /api/agents/verify — verify email with 6-digit code to get API key Changes: - openapi.json: new paths + 4 component schemas - api-reference/agents/signup.mdx and verify.mdx (frontmatter-only) - docs.json: Agent Onboarding group in Accounts tab - quickstart.mdx: Agent Onboarding section with curl examples - index.mdx: Agent Signup card + LLM reference line - authentication.mdx: Agent Onboarding section Co-Authored-By: Paperclip <noreply@paperclip.ing>
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds documentation, navigation, quickstart/index updates, and OpenAPI specs for two unauthenticated agent onboarding endpoints: POST /api/agents/signup and POST /api/agents/verify, with request/response schemas, examples, and notes about api_key issuance and verification flows. Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant API_Server
participant DB
participant Email_Service
Client->>API_Server: POST /api/agents/signup { email }
API_Server->>DB: lookup/create account, decide whether to issue key
alt email starts with "agent+"
API_Server->>DB: persist new api_key
API_Server-->>Client: 200 { api_key, account_id, message }
else standard email
API_Server->>DB: store verification code
API_Server->>Email_Service: send 6-digit code
API_Server-->>Client: 200 { api_key: null, account_id, message }
end
Client->>API_Server: POST /api/agents/verify { email, code }
API_Server->>DB: validate code
alt valid
API_Server->>DB: create/return api_key
API_Server-->>Client: 200 { api_key, account_id, message }
else invalid/expired
API_Server-->>Client: 400 or 429
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (1)
quickstart.mdx (1)
14-47: Consider extracting onboarding flow text into a shared snippet.The same behavioral rules are now documented in multiple pages (
quickstart.mdxandauthentication.mdx), which increases drift risk when endpoint behavior changes.As per coding guidelines, "Follow DRY principle - don't duplicate content across pages, use snippets."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@quickstart.mdx` around lines 14 - 47, Extract the duplicated "Agent Onboarding" content into a single reusable MDX snippet (e.g., onboarding-agent-signup) and replace the inline section in quickstart.mdx (the "Agent Onboarding" heading and the three curl examples/Info block) with an import/include of that snippet; do the same replacement in authentication.mdx so both pages reference the single snippet, ensuring the snippet contains the instant signup, standard signup, verify examples and the Info reference.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@api-reference/openapi.json`:
- Around line 15616-15620: The account_id property in the two response schemas
is declared as a plain string but should be typed as a UUID; update both
occurrences of the "account_id" property in the response schemas (the ones
describing the verified agent/account) to include "format": "uuid" alongside
"type": "string" (keep the existing description and example) so the OpenAPI
contract and generated SDK typings reflect a UUID.
- Around line 15601-15605: The "code" schema currently allows any string but
should be constrained to a 6-digit numeric value; update the "code" property in
the OpenAPI schema (the "code" field under the relevant request/response schema)
to include numeric pattern and length constraints by adding minLength: 6,
maxLength: 6 and a pattern like "^[0-9]{6}$" so generated clients validate a
six-digit numeric verification code.
In `@authentication.mdx`:
- Around line 107-120: Update the top-level auth rule in the Overview of
authentication.mdx to acknowledge the documented unauthenticated exceptions:
explicitly state that while most API requests require authentication, the
endpoints POST /api/agents/signup and POST /api/agents/verify are
unauthenticated for agent onboarding (signup and verification flow described in
the "Agent Onboarding" section), and clarify that these endpoints
return/generate API keys as described; adjust the Overview text accordingly so
it no longer asserts that "every request must be authenticated" without
exception.
In `@index.mdx`:
- Line 161: Update the Authentication section to explicitly document the
exception for onboarding endpoints: state that while most API endpoints require
API-key authentication, any routes under /api/agents/* used for agent onboarding
(signup, verify) are unauthenticated and should be called without an API key;
reference the specific path "/api/agents/*" and the onboarding actions (signup,
verify) in the paragraph so integrators know not to send API-key auth for those
calls and to treat them as public endpoints.
---
Nitpick comments:
In `@quickstart.mdx`:
- Around line 14-47: Extract the duplicated "Agent Onboarding" content into a
single reusable MDX snippet (e.g., onboarding-agent-signup) and replace the
inline section in quickstart.mdx (the "Agent Onboarding" heading and the three
curl examples/Info block) with an import/include of that snippet; do the same
replacement in authentication.mdx so both pages reference the single snippet,
ensuring the snippet contains the instant signup, standard signup, verify
examples and the Info reference.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: d7514d82-0725-48bf-978d-b38f0dd65d38
📒 Files selected for processing (7)
api-reference/agents/signup.mdxapi-reference/agents/verify.mdxapi-reference/openapi.jsonauthentication.mdxdocs.jsonindex.mdxquickstart.mdx
Comment on lines
+15601
to
+15605
| "code": { | ||
| "type": "string", | ||
| "description": "The 6-digit verification code sent to the email.", | ||
| "example": "123456" | ||
| } |
There was a problem hiding this comment.
Constrain verification code to the documented 6-digit format.
Line 15603 says “6-digit verification code”, but the schema currently accepts any string. Add length and numeric pattern constraints so generated clients validate correctly.
Suggested schema fix
"code": {
"type": "string",
+ "minLength": 6,
+ "maxLength": 6,
+ "pattern": "^[0-9]{6}$",
"description": "The 6-digit verification code sent to the email.",
"example": "123456"
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| "code": { | |
| "type": "string", | |
| "description": "The 6-digit verification code sent to the email.", | |
| "example": "123456" | |
| } | |
| "code": { | |
| "type": "string", | |
| "minLength": 6, | |
| "maxLength": 6, | |
| "pattern": "^[0-9]{6}$", | |
| "description": "The 6-digit verification code sent to the email.", | |
| "example": "123456" | |
| } |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@api-reference/openapi.json` around lines 15601 - 15605, The "code" schema
currently allows any string but should be constrained to a 6-digit numeric
value; update the "code" property in the OpenAPI schema (the "code" field under
the relevant request/response schema) to include numeric pattern and length
constraints by adding minLength: 6, maxLength: 6 and a pattern like "^[0-9]{6}$"
so generated clients validate a six-digit numeric verification code.
Comment on lines
+15616
to
+15620
| "account_id": { | ||
| "type": "string", | ||
| "description": "The account ID for the verified agent.", | ||
| "example": "123e4567-e89b-12d3-a456-426614174000" | ||
| }, |
There was a problem hiding this comment.
Mark account_id as UUID in both new response schemas.
Line 15616 and Line 15668 define account IDs as plain strings despite UUID examples/descriptions. Adding format: "uuid" improves contract precision and SDK typing.
Suggested schema fix
"account_id": {
"type": "string",
+ "format": "uuid",
"description": "The account ID for the verified agent.",
"example": "123e4567-e89b-12d3-a456-426614174000"
} "account_id": {
"type": "string",
+ "format": "uuid",
"description": "The account ID for the registered agent.",
"example": "123e4567-e89b-12d3-a456-426614174000"
}Also applies to: 15668-15672
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@api-reference/openapi.json` around lines 15616 - 15620, The account_id
property in the two response schemas is declared as a plain string but should be
typed as a UUID; update both occurrences of the "account_id" property in the
response schemas (the ones describing the verified agent/account) to include
"format": "uuid" alongside "type": "string" (keep the existing description and
example) so the OpenAPI contract and generated SDK typings reflect a UUID.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
3 issues found across 7 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="authentication.mdx">
<violation number="1" location="authentication.mdx:109">
P2: This section documents unauthenticated endpoints, but the page's opening Overview still states that every request must be authenticated. Update the Overview paragraph to note the Agent Onboarding exception, otherwise integrators reading top-to-bottom will get conflicting guidance.</violation>
</file>
<file name="index.mdx">
<violation number="1" location="index.mdx:161">
P2: This adds an unauthenticated endpoint group, but the same page still says all API endpoints require `x-api-key`. Update the surrounding auth guidance so agent onboarding is documented consistently.</violation>
</file>
<file name="api-reference/openapi.json">
<violation number="1" location="api-reference/openapi.json:15554">
P2: The `code` field is described as a "6-digit verification code" but the schema has no `minLength`, `maxLength`, or `pattern` constraint — any string will pass validation. Add `"minLength": 6, "maxLength": 6, "pattern": "^[0-9]{6}$"` so generated SDKs and docs enforce the expected format.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.
|
|
||
| --- | ||
|
|
||
| ## Agent Onboarding |
Collaborator
There was a problem hiding this comment.
Move this to a different guide.
- actual: authentication.mdx
- required: agents.mdx
Resolve conflicts from the openapi.json split (#121): - Port agent signup/verify paths and schemas into openapi/accounts.json - Update agents/{signup,verify}.mdx frontmatter to new openapi path - Accept deletion of monolithic openapi.json - Keep both Agent Onboarding and Connectors groups in docs.json Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
| }, | ||
| "/api/agents/signup": { | ||
| "post": { | ||
| "description": "Register an agent. For new agent+ emails, returns an API key immediately. For all other cases, sends a verification code to the email — call /api/agents/verify with the code to get your API key.", |
Collaborator
There was a problem hiding this comment.
Make a note here, if unsure what email to register, use agent+{todaysDate}@recoupable.com to make it as easy as possible for an agent to create a new api key.
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
api-reference/openapi/accounts.json (1)
1482-1493: Consider documenting non-200 outcomes for/api/agents/signup.Right now only
200is specified. For a public signup endpoint, documenting expected validation/rate-limit errors improves generated client behavior and error handling.Suggested OpenAPI response additions
"responses": { "200": { "description": "Signup processed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSignupResponse" } } } + }, + "400": { + "description": "Invalid request payload", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Too many signup attempts", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api-reference/openapi/accounts.json` around lines 1482 - 1493, Add non-200 responses to the /api/agents/signup operation to document likely error cases: include a 400 (or 422) with a ValidationError schema for input validation failures, a 429 with a RateLimitError schema for throttling, and a 500 (or default) with a generic ErrorResponse schema for server errors; reference the existing AgentSignupResponse success schema and add new components/schemas like ValidationError, RateLimitError, and ErrorResponse, then add those response objects to the "responses" map for the signup operation so generated clients can handle validation, rate-limit, and server errors explicitly.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@api-reference/openapi/accounts.json`:
- Around line 2752-2756: The account_id response field is missing the UUID
format; update the JSON Schema entries for "account_id" (the property named
account_id in the responses) to include "format": "uuid" alongside "type":
"string" so clients can validate as UUIDs; apply the same change to both
occurrences of the account_id response fields (the one shown and the second
occurrence referenced) by adding the format key to each account_id property in
the OpenAPI JSON.
- Around line 2785-2788: The "code" property in the accounts OpenAPI schema
currently allows any string; constrain it to a 6-digit numeric string by
updating the "code" schema (the "code" property in
api-reference/openapi/accounts.json) to include a regex pattern and length
constraints (e.g., add "pattern": "^[0-9]{6}$" and/or "minLength": 6 and
"maxLength": 6) so only exactly six numeric characters are valid.
---
Nitpick comments:
In `@api-reference/openapi/accounts.json`:
- Around line 1482-1493: Add non-200 responses to the /api/agents/signup
operation to document likely error cases: include a 400 (or 422) with a
ValidationError schema for input validation failures, a 429 with a
RateLimitError schema for throttling, and a 500 (or default) with a generic
ErrorResponse schema for server errors; reference the existing
AgentSignupResponse success schema and add new components/schemas like
ValidationError, RateLimitError, and ErrorResponse, then add those response
objects to the "responses" map for the signup operation so generated clients can
handle validation, rate-limit, and server errors explicitly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 4cad014f-915f-4d27-b2d2-0d4edcf74f51
📒 Files selected for processing (4)
api-reference/agents/signup.mdxapi-reference/agents/verify.mdxapi-reference/openapi/accounts.jsondocs.json
✅ Files skipped from review due to trivial changes (3)
- api-reference/agents/signup.mdx
- api-reference/agents/verify.mdx
- docs.json
- Move Agent Onboarding section from authentication.mdx to new agents.mdx guide (per @sweetmantech), surface it in the Agents nav group - Add the agent+{todaysDate}@recoupable.com tip to the signup endpoint description and agents.mdx - Note the agent onboarding exception in authentication.mdx overview and index.mdx auth section so the "all requests must be auth'd" rule is internally consistent - Constrain AgentVerifyRequest.code to a 6-digit numeric pattern - Mark account_id as format: uuid in AgentSignupResponse and AgentVerifyResponse Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
1 issue found across 5 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="agents.mdx">
<violation number="1" location="agents.mdx:22">
P2: Custom agent: **Flag AI Slop and Fabricated Changes**
These curl examples (instant signup, standard signup, verify) duplicate content already present in `quickstart.mdx` with only cosmetic differences (full JSON response blocks here vs. inline comments there). The repo guidelines call for DRY via reusable `snippets/`. Extract the shared examples into a snippet and include it from both pages.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.
| @@ -0,0 +1,67 @@ | |||
| --- | |||
There was a problem hiding this comment.
P2: Custom agent: Flag AI Slop and Fabricated Changes
These curl examples (instant signup, standard signup, verify) duplicate content already present in quickstart.mdx with only cosmetic differences (full JSON response blocks here vs. inline comments there). The repo guidelines call for DRY via reusable snippets/. Extract the shared examples into a snippet and include it from both pages.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At agents.mdx, line 22:
<comment>These curl examples (instant signup, standard signup, verify) duplicate content already present in `quickstart.mdx` with only cosmetic differences (full JSON response blocks here vs. inline comments there). The repo guidelines call for DRY via reusable `snippets/`. Extract the shared examples into a snippet and include it from both pages.</comment>
<file context>
@@ -0,0 +1,67 @@
+## Instant Signup (agent+ prefix)
+
+```bash
+curl -X POST "https://recoup-api.vercel.app/api/agents/signup" \
+ -H "Content-Type: application/json" \
+ -d '{"email": "agent+mybot@example.com"}'
</file context>
| }, | ||
| "/api/agents/signup": { | ||
| "post": { | ||
| "description": "Register an agent. For new agent+ emails, returns an API key immediately. For all other cases, sends a verification code to the email — call /api/agents/verify with the code to get your API key.\n\n**Tip:** If you're unsure what email to register, use `agent+{todaysDate}@recoupable.com` (e.g. `agent+2026-04-11@recoupable.com`). This guarantees the `agent+` prefix path and returns an API key instantly — no email verification needed.", |
Collaborator
There was a problem hiding this comment.
Update /api/agents/verify with a hyperlink to the docs page mentioned.
Collaborator
There was a problem hiding this comment.
Update the date example to include time up to milliseconds to allow multiple agent sign ups within the same second.
| Multiple API keys per account are supported — each signup or verification generates a new key without revoking existing ones. | ||
|
|
||
| <Info> | ||
| If you're unsure what email to register, use `agent+{todaysDate}@recoupable.com` (e.g. `agent+2026-04-11@recoupable.com`). This guarantees the `agent+` prefix path — you'll receive an API key instantly on the first response without needing email verification. |
Collaborator
There was a problem hiding this comment.
Same note here to update the example to include milliseconds to allow multiple agent sign ups in the same second.
| ## Authentication | ||
|
|
||
| All API endpoints are authenticated using an API key passed in the `x-api-key` header. | ||
| Most API endpoints are authenticated using an API key passed in the `x-api-key` header. The only exceptions are the [agent onboarding](/agents) endpoints (`POST /api/agents/signup` and `POST /api/agents/verify`), which are intentionally unauthenticated so agents can obtain their first API key. |
Collaborator
There was a problem hiding this comment.
Update the 2 mentioned API endpoints to include hyperlinks to the mentioned endpoint docs.
- Link /api/agents/verify in the signup endpoint description
- Switch the easy-email tip to agent+{Date.now()}@recoupable.com so
agents signing up within the same second still get unique addresses
(applied in agents.mdx and the OpenAPI description)
- Hyperlink both /api/agents/signup and /api/agents/verify in the
index.mdx authentication section
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
sweetmantech
approved these changes
Apr 11, 2026
Restructure the top-level pages so an AI agent landing cold on the docs can copy one curl command and have a working API key. Inspired by AgentMail's quickstart layout, but the agent+ prefix trick lets us skip their OTP round-trip entirely. - index.mdx: add a "Quickest start — one curl call" section right under the hero, and promote Agent Signup to the first card in Get Started (removed the duplicate card from the Agents group below) - quickstart.mdx: lead with "## Quickest start" (single curl call using agent+$(date +%s%3N) for guaranteed uniqueness), move the dashboard path to a "Prefer the dashboard?" section at the bottom, trim the duplicated three-step onboarding block in favor of a link to /agents (closes the cubic-dev-ai DRY duplication comment) - agents.mdx: restructured as an action-first runbook — "Quickest start" heading first, single copy-paste curl block, then "How it works", with the standard email-verification flow demoted to a secondary section Mintlify already publishes /llms.txt automatically, so no action needed on that front — the new endpoints will be indexed on the next deploy. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@agents.mdx`:
- Line 13: Replace the non-portable timestamp expression in the JSON payload
string '{"email": "agent+'$(date +%s%3N)'@recoupable.com"}' with a
shell-portable millisecond timestamp approach: compute a seconds-based epoch
(e.g., using printf '%(%s)T' -1 and multiply by 1000) or, when using bash 5+,
use $EPOCHREALTIME for higher precision, then inject that computed value into
the email string instead of $(date +%s%3N) so the example works on macOS/BSD and
GNU systems.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: f217dd14-3e42-45ea-9a40-5489d7c7170e
📒 Files selected for processing (4)
agents.mdxapi-reference/openapi/accounts.jsonindex.mdxquickstart.mdx
✅ Files skipped from review due to trivial changes (1)
- api-reference/openapi/accounts.json
🚧 Files skipped from review as they are similar to previous changes (2)
- quickstart.mdx
- index.mdx
There was a problem hiding this comment.
5 issues found across 3 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="index.mdx">
<violation number="1" location="index.mdx:15">
P2: Custom agent: **Flag AI Slop and Fabricated Changes**
This entire "Quickest start" section (heading, description, curl block) is duplicated nearly verbatim across `index.mdx`, `quickstart.mdx`, and `agents.mdx`. The repo's own principles require using the `snippets/` directory to avoid duplicating content across pages. Extract the shared curl example into a snippet and include it from all three files.</violation>
<violation number="2" location="index.mdx:17">
P2: `date +%s%3N` is a GNU coreutils extension — macOS's BSD `date` doesn't support `%N` and will output literal characters. Use `$(date +%s)` (seconds-only, still unique enough) or add a note about GNU date to avoid confusing macOS users who copy-paste this.</violation>
</file>
<file name="agents.mdx">
<violation number="1" location="agents.mdx:13">
P2: `$(date +%s%3N)` is not portable — on macOS (BSD `date`), `%3N` is unsupported and will be output literally, producing a malformed email address. Consider using a portable alternative or adding a note about platform differences.</violation>
<violation number="2" location="agents.mdx:13">
P2: `date +%s%3N` is a GNU coreutils extension and does not work on macOS/BSD — it outputs the literal string `%3N` instead of milliseconds, producing a malformed email address. Since this is the primary quickstart example, macOS users will get a broken curl command. Consider using a portable alternative such as `$(date +%s)000` (second-precision with padding) or `$(python3 -c 'import time; print(int(time.time()*1000))')`.</violation>
</file>
<file name="quickstart.mdx">
<violation number="1" location="quickstart.mdx:13">
P2: `date +%s%3N` is not portable — `%3N` (truncated nanoseconds) is a GNU extension and fails on macOS's BSD `date`, outputting literal `3N`. Since this is a copy-paste curl example, use `%s` (epoch seconds) which is POSIX-portable and still unique enough.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.
| Get a working API key in a single unauthenticated request. No dashboard, no browser, no human in the loop. | ||
|
|
||
| ```bash | ||
| curl -X POST "https://recoup-api.vercel.app/api/agents/signup" \ |
There was a problem hiding this comment.
P2: Custom agent: Flag AI Slop and Fabricated Changes
This entire "Quickest start" section (heading, description, curl block) is duplicated nearly verbatim across index.mdx, quickstart.mdx, and agents.mdx. The repo's own principles require using the snippets/ directory to avoid duplicating content across pages. Extract the shared curl example into a snippet and include it from all three files.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At index.mdx, line 15:
<comment>This entire "Quickest start" section (heading, description, curl block) is duplicated nearly verbatim across `index.mdx`, `quickstart.mdx`, and `agents.mdx`. The repo's own principles require using the `snippets/` directory to avoid duplicating content across pages. Extract the shared curl example into a snippet and include it from all three files.</comment>
<file context>
@@ -7,6 +7,18 @@ description: "Use the Recoup API to build your record label. Access research, co
+Get a working API key in a single unauthenticated request. No dashboard, no browser, no human in the loop.
+
+```bash
+curl -X POST "https://recoup-api.vercel.app/api/agents/signup" \
+ -H "Content-Type: application/json" \
+ -d '{"email": "agent+'$(date +%s%3N)'@recoupable.com"}'
</file context>
Drop the returned api_key straight into \$RECOUP_API_KEY in a single shell command, so agents can pipe signup → usage with no intermediate copy-paste step. - index.mdx: the Quickest Start block now exports RECOUP_API_KEY directly - quickstart.mdx: same one-liner, plus a verification call using the exported env var - agents.mdx: added a dedicated Tip callout showing both the signup one-liner and a follow-up request against /api/accounts/id Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
♻️ Duplicate comments (1)
agents.mdx (1)
13-13:⚠️ Potential issue | 🟡 MinorUse a shell-portable millisecond timestamp in both signup examples.
Line 13 and Line 34 use
date +%s%3N, which is GNU-specific and breaks on macOS/BSD shells. This can make the “quickest start” and export one-liner fail for a large set of users.Suggested doc patch
-curl -X POST "https://recoup-api.vercel.app/api/agents/signup" \ - -H "Content-Type: application/json" \ - -d '{"email": "agent+'$(date +%s%3N)'@recoupable.com"}' +printf -v ts '%(%s)T' -1; ms=$((ts * 1000)) +curl -X POST "https://recoup-api.vercel.app/api/agents/signup" \ + -H "Content-Type: application/json" \ + -d '{"email":"agent+'"$ms"'@recoupable.com"}'-export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agents/signup" \ - -H "Content-Type: application/json" \ - -d '{"email": "agent+'$(date +%s%3N)'@recoupable.com"}' | jq -r .api_key) +printf -v ts '%(%s)T' -1; ms=$((ts * 1000)) +export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agents/signup" \ + -H "Content-Type: application/json" \ + -d '{"email":"agent+'"$ms"'@recoupable.com"}' | jq -r .api_key)Does `date +%s%3N` work on both GNU/Linux and BSD/macOS `date`? What is a portable Bash-compatible way to generate epoch milliseconds for shell examples?Also applies to: 34-34
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@agents.mdx` at line 13, Replace the GNU-specific timestamp usage "date +%s%3N" used in the signup and export one-line examples with a shell-portable epoch-milliseconds generator; update both occurrences (the two signup examples) so they instead invoke a portable inline command (for example, calling python3 to compute int(time.time()*1000)) and use that substitution in place of "date +%s%3N" so the examples work on both Linux and macOS/BSD shells.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@agents.mdx`:
- Line 13: Replace the GNU-specific timestamp usage "date +%s%3N" used in the
signup and export one-line examples with a shell-portable epoch-milliseconds
generator; update both occurrences (the two signup examples) so they instead
invoke a portable inline command (for example, calling python3 to compute
int(time.time()*1000)) and use that substitution in place of "date +%s%3N" so
the examples work on both Linux and macOS/BSD shells.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 3a5e4325-5758-41db-b3ab-a192a86ea107
📒 Files selected for processing (3)
agents.mdxindex.mdxquickstart.mdx
🚧 Files skipped from review as they are similar to previous changes (2)
- index.mdx
- quickstart.mdx
\`date +%s%3N\` is a GNU coreutils extension — on macOS's BSD \`date\`, \`%3N\` is output literally, producing a broken, non-unique email like \`agent+17449811573N@recoupable.com\`. Since most developers copy-pasting our quickstart are on macOS, this would silently give them duplicate suffixes within the same second and confuse the \`agent+\` onboarding flow. Switch to \`\$(date +%s)-\$RANDOM\`, which is: - Portable across BSD/GNU \`date\` (POSIX \`%s\` only) - Collision-free within a single second (bash/zsh \`\$RANDOM\` adds 0–32767 of entropy per call) - Still trivially readable in curl examples Applied in index.mdx, quickstart.mdx, agents.mdx, and the /api/agents/signup OpenAPI description. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
sweetmantech
approved these changes
Apr 12, 2026
6 tasks
This was referenced May 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
POST /api/agents/signupandPOST /api/agents/verifyapi-reference/agents/(frontmatter-only, auto-generated from OpenAPI)quickstart.mdxwith curl examples for both flowsindex.mdxauthentication.mdxexplaining the two endpointsTest plan
npx mintlify@latest devand verify Agent Signup + Verify pages render from OpenAPI/api/agents/*line🤖 Generated with Claude Code
Summary by cubic
Adds unauthenticated agent onboarding docs and OpenAPI so agents can sign up and verify by email to get API keys. Makes the one-call
agent+signup the primary path and adds a one-liner that exportsRECOUP_API_KEYfor immediate use.New Features
POST /api/agents/signupandPOST /api/agents/verifywithAgentSignup*/AgentVerify*schemas; enforce 6‑digit numericcodeanduuidformats; unauthenticated; signup description links to verify.RECOUP_API_KEYand a follow-up/api/accounts/idverification call; Agent Signup card promoted; API reference under Accounts > Agent Onboarding; auth sections clarify these unauthenticated endpoints; LLM reference lists/api/agents/*.Refactors
api-reference/openapi/accounts.jsonand update MDX frontmatter; keep both “Agent Onboarding” and “Connectors” nav groups; addagentsto the Agents nav.authentication.mdxinto the newagents.mdx; de-duplicate Quickstart and move the dashboard path to a “Prefer the dashboard?” section.$(date +%s)-$RANDOMin examples and OpenAPI tips to avoid macOS%3Nissues and ensure uniqueagent+emails.Written for commit f786b58. Summary will update on new commits.
Summary by CodeRabbit
New Features
Documentation