docs: Agent Signup & Verify endpoints#104
Open
recoup-coding-agent wants to merge 1 commit intomainfrom
Open
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>
📝 WalkthroughWalkthroughThis PR introduces documentation and OpenAPI specifications for two new unauthenticated agent onboarding endpoints: Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
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 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.
Comment on lines
+107
to
+120
| ## Agent Onboarding | ||
|
|
||
| Two unauthenticated endpoints allow agents to create accounts and obtain API keys programmatically: | ||
|
|
||
| - **`POST /api/agents/signup`** — Register with an email address. Emails with the `agent+` prefix (e.g. `agent+mybot@example.com`) receive an API key immediately on first signup. All other cases receive a 6-digit verification code via email. | ||
| - **`POST /api/agents/verify`** — Submit the verification code to receive an API key. | ||
|
|
||
| Multiple API keys per account are supported — each signup or verification generates a new key without revoking existing ones. | ||
|
|
||
| <Info> | ||
| See the [Agent Signup](/api-reference/agents/signup) and [Verify](/api-reference/agents/verify) API reference for request/response details. | ||
| </Info> | ||
|
|
||
| --- |
There was a problem hiding this comment.
This section conflicts with the page’s top-level auth rule.
The new onboarding section correctly describes unauthenticated endpoints, but the Overview (Line 8) still states every request must be authenticated. Please update the opening rule to include this documented exception.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@authentication.mdx` around lines 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.
| - **`/api/organizations/*`** — Organizations (list, create, add-artist) | ||
| - **`/api/sandboxes/*`** — Sandboxes (list, create, snapshot, delete, setup, file, upload) | ||
| - **`/api/content-agent/*`** — Content agent webhooks (webhook, callback) | ||
| - **`/api/agents/*`** — Agent onboarding (signup, verify) — no auth required |
There was a problem hiding this comment.
Auth guidance is now internally inconsistent on this page.
Line 161 documents unauthenticated /api/agents/*, but Line 26 still says all endpoints require API-key auth. Please add an explicit exception in the Authentication section so integrators don’t mis-implement onboarding calls.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@index.mdx` at 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.
![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 | ||
|
|
||
| Two unauthenticated endpoints allow agents to create accounts and obtain API keys programmatically: |
There was a problem hiding this comment.
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.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At authentication.mdx, line 109:
<comment>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.</comment>
<file context>
@@ -104,6 +104,21 @@ Some endpoints accept an `organization_id` parameter. When provided, the API add
+## Agent Onboarding
+
+Two unauthenticated endpoints allow agents to create accounts and obtain API keys programmatically:
+
+- **`POST /api/agents/signup`** — Register with an email address. Emails with the `agent+` prefix (e.g. `agent+mybot@example.com`) receive an API key immediately on first signup. All other cases receive a 6-digit verification code via email.
</file context>
| - **`/api/organizations/*`** — Organizations (list, create, add-artist) | ||
| - **`/api/sandboxes/*`** — Sandboxes (list, create, snapshot, delete, setup, file, upload) | ||
| - **`/api/content-agent/*`** — Content agent webhooks (webhook, callback) | ||
| - **`/api/agents/*`** — Agent onboarding (signup, verify) — no auth required |
There was a problem hiding this comment.
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.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At index.mdx, line 161:
<comment>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.</comment>
<file context>
@@ -151,6 +158,7 @@ If you are an LLM navigating these docs, here is a summary of the endpoint struc
- **`/api/organizations/*`** — Organizations (list, create, add-artist)
- **`/api/sandboxes/*`** — Sandboxes (list, create, snapshot, delete, setup, file, upload)
- **`/api/content-agent/*`** — Content agent webhooks (webhook, callback)
+- **`/api/agents/*`** — Agent onboarding (signup, verify) — no auth required
Base URL: `https://recoup-api.vercel.app/api`
</file context>
| ], | ||
| "properties": { | ||
| "email": { | ||
| "type": "string", |
There was a problem hiding this comment.
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.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/openapi.json, line 15554:
<comment>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.</comment>
<file context>
@@ -15465,6 +15543,92 @@
+ ],
+ "properties": {
+ "email": {
+ "type": "string",
+ "format": "email",
+ "description": "The agent email address. Emails with the agent+ prefix (e.g. agent+mybot@example.com) get an API key immediately on first signup.",
</file context>
Suggested change
| "type": "string", | |
| "type": "string", | |
| "minLength": 6, | |
| "maxLength": 6, | |
| "pattern": "^[0-9]{6}$", |
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
1 participant
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 documentation and OpenAPI for unauthenticated Agent Onboarding so agents can sign up and verify by email to get API keys. Updates quickstart, authentication, and navigation to surface both instant
agent+and standard verify flows.POST /api/agents/signupandPOST /api/agents/verifywithAgentSignup*andAgentVerify*schemas.api-reference/agents/signupandapi-reference/agents/verify(auto-generated).agent+signup and verification flow./api/agents/*line in the LLM reference.Written for commit 322e396. Summary will update on new commits.
Summary by CodeRabbit
New Features
Documentation