Update API specifications with fern api update #4405
Closed
+411
−3
Conversation
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
Contributor
WalkthroughA single OpenAPI specification file was updated to introduce four new billing endpoints ( Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested reviewers
Poem
Pre-merge checks❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
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 |
![ellipsis-dev[bot]](https://avatars.githubusercontent.com/in/64358?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Important
Looks good to me! 👍
Reviewed everything up to 6862abc in 2 minutes and 17 seconds. Click for details.
- Reviewed
481lines of code in1files - Skipped
0files when reviewing. - Skipped posting
4draft comments. View those below. - Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.
1. fern/openapi/skyvern_openapi.json:2952
- Draft comment:
x-api-key header is set as optional (required: false). If authentication is mandatory, consider marking it as required. - Reason this comment was not posted:
Confidence changes required:50%<= threshold50%None
2. fern/openapi/skyvern_openapi.json:5340
- Draft comment:
For consistency, consider using a $ref to '#/components/schemas/PlanTier' for the 'tier' property in ChangeTierResponse (as done in ChangeTierRequest) instead of using a plain string. - Reason this comment was not posted:
Comment was not on a location in the diff, so it can't be submitted as a review comment.
3. fern/openapi/skyvern_openapi.json:2975
- Draft comment:
The x-api-key header parameter is repeated across multiple endpoints. Consider defining a reusable header parameter to reduce duplication. - Reason this comment was not posted:
Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 20% vs. threshold = 50% This is a code quality refactoring suggestion about OpenAPI spec structure. While it's technically correct that there's duplication, I need to consider: 1) This is an OpenAPI JSON file that is likely auto-generated from code (common pattern with FastAPI/similar frameworks), 2) The comment is about refactoring/code quality, not a bug, 3) Looking at the existing endpoints in the file (not shown in diff but referenced), they likely also have this same duplication pattern, meaning this is consistent with the existing codebase style, 4) The rules say "Comments that suggest code quality refactors are good! But only if they are actionable and clear" - but for auto-generated OpenAPI specs, manually refactoring them is often not the right approach since they get regenerated. I might be wrong about this being auto-generated - it could be manually maintained. Also, even if auto-generated, there might be ways to configure the generation to use reusable components. The comment is actionable and clear about what should be done. While the comment is technically correct and actionable, OpenAPI JSON files are typically auto-generated from backend code annotations/decorators. If this file is auto-generated (which is the standard practice), then manually editing it to use reusable components would be counterproductive as changes would be overwritten on next generation. The proper fix would be in the code generation configuration or backend code, not in this JSON file. Without strong evidence that this file is manually maintained, and given that similar duplication likely exists throughout the file in existing endpoints, this comment is likely not useful. This comment should be deleted. It's a refactoring suggestion for an OpenAPI spec file that is almost certainly auto-generated, making manual refactoring inappropriate. The duplication pattern is likely consistent throughout the existing codebase.
4. fern/openapi/skyvern_openapi.json:3505
- Draft comment:
BillingStateResponse includes nullable fields (e.g. current_period_start/end) in the required list. Confirm if null values are expected; otherwise, consider making these fields optional. - Reason this comment was not posted:
Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 10% vs. threshold = 50% In OpenAPI/JSON Schema, having a field in the "required" array means the field key must be present in the JSON object. The "anyOf" with null type means the field can have a null value. These are not mutually exclusive - a field can be required to be present but allowed to have a null value. This is actually a common and valid pattern. The comment seems to misunderstand this distinction and is asking for confirmation about something that is perfectly valid. This is speculative ("Confirm if...") and doesn't point to a definite issue. The comment also says "consider making these fields optional" which is a suggestion without strong evidence of a problem. I might be missing context about the business logic - perhaps these fields should never be null in practice, and the schema is incorrectly permissive. However, without seeing the actual implementation or understanding the business requirements, I cannot determine if this is truly an issue. The comment is asking the PR author to "confirm" something and uses the word "consider", which are both red flags according to the rules. The comment is speculative and doesn't identify a definite problem. The schema definition is technically valid in OpenAPI, and without strong evidence that this is wrong, the comment should be deleted. This comment should be deleted. It's asking for confirmation and making a speculative suggestion without strong evidence of an actual problem. The schema definition is technically valid in OpenAPI (required + nullable is a common pattern), and the comment doesn't demonstrate a clear code change that's needed.
Workflow ID: wflow_D573XadoJusYnz2X
You can customize 
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @fern/openapi/skyvern_openapi.json:
- Around line 2953-3175: The OpenAPI spec for
create_checkout_session_api_v1_billing_checkout_post is missing the documented
400 response: add a "400" responses entry with description "Org already has an
active subscription; use portal instead." to the "/api/v1/billing/checkout" POST
responses so client generators include it. Also verify the path prefix
consistency for all billing endpoints (currently "/api/v1/billing/...") against
the project's public API convention (e.g., "/v1/..."); if the intended prefix is
"/v1/billing/..." rename the paths and update the operationId tokens accordingly
(e.g., create_checkout_session_api_v1_billing_checkout_post → adjust to match
the new path).
🧹 Nitpick comments (1)
fern/openapi/skyvern_openapi.json (1)
4616-4705: Billing schemas andPlanTierwiring look coherent; consider tighteningChangeTierResponse.tier
PlanTierandBillingStateResponseare wired consistently, and bothCheckoutSubscriptionRequest.tierandChangeTierRequest.tiercorrectly referencePlanTier, which is good for generated SDK enums and validation.- In
ChangeTierResponse, however,tieris currently a plainstring. If the API always returns one of thePlanTiervalues here, you could strengthen the contract by referencingPlanTierinstead, which will make client types more precise.Optional schema tweak for `ChangeTierResponse.tier`
"ChangeTierResponse": { "properties": { "status": { "type": "string", "title": "Status" }, - "tier": { - "type": "string", - "title": "Tier" - } + "tier": { + "$ref": "#/components/schemas/PlanTier" + } }, "type": "object", "required": [ "status", "tier" ], "title": "ChangeTierResponse" },Also applies to: 5658-5717, 11885-11907
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
fern/openapi/skyvern_openapi.json
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Run tests and pre-commit hooks
🔇 Additional comments (2)
fern/openapi/skyvern_openapi.json (2)
3504-3514: Newscreenshot_artifact_idonActionis backward‑compatible and well‑typedThe added
screenshot_artifact_idis optional (string|null) and not added to therequiredlist, so it’s safe for existing clients while enabling richer linkage to screenshot artifacts at the action level. This looks consistent with how other optional properties are modeled.
6331-6340: Proxy location additions forRESIDENTIAL_PHare consistent across enum and docsThe new
RESIDENTIAL_PHvalue is:
- added to the
ProxyLocationenum, and- documented in the proxy location descriptions for
CreateBrowserSessionRequest,TaskRunRequest, andWorkflowRunRequest.This keeps the enum and narrative docs in sync and preserves the existing notes about deprecated
US-*values routing viaRESIDENTIAL_ISP. Looks good.Also applies to: 13519-13537, 17436-17455, 11987-12015
Comment on lines
+2953
to
3175
| "/api/v1/billing/checkout": { | ||
| "post": { | ||
| "summary": "Create Checkout Session", | ||
| "description": "Create a Stripe Checkout Session for subscribing to a tier.\n\nFrontend should redirect the user to the returned URL.\nAfter successful checkout, Stripe will send a webhook that we handle\nto store the subscription and initialize billing state.\n\nReturns 400 if org already has an active subscription (use portal instead).", | ||
| "operationId": "create_checkout_session_api_v1_billing_checkout_post", | ||
| "parameters": [ | ||
| { | ||
| "name": "x-api-key", | ||
| "in": "header", | ||
| "required": false, | ||
| "schema": { | ||
| "anyOf": [ | ||
| { | ||
| "type": "string" | ||
| }, | ||
| { | ||
| "type": "null" | ||
| } | ||
| ], | ||
| "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.", | ||
| "title": "X-Api-Key" | ||
| }, | ||
| "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings." | ||
| } | ||
| ], | ||
| "requestBody": { | ||
| "required": true, | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/CheckoutSubscriptionRequest" | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "responses": { | ||
| "200": { | ||
| "description": "Successful Response", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/CheckoutSessionResponse" | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "422": { | ||
| "description": "Validation Error", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/HTTPValidationError" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "/api/v1/billing/portal": { | ||
| "post": { | ||
| "summary": "Create Portal Session", | ||
| "description": "Create a Stripe Customer Portal session for managing subscription.\n\nFrontend should redirect the user to the returned URL.\nThe portal allows users to:\n- Update payment methods\n- Upgrade/downgrade plans\n- Cancel subscription\n- View invoices", | ||
| "operationId": "create_portal_session_api_v1_billing_portal_post", | ||
| "parameters": [ | ||
| { | ||
| "name": "x-api-key", | ||
| "in": "header", | ||
| "required": false, | ||
| "schema": { | ||
| "anyOf": [ | ||
| { | ||
| "type": "string" | ||
| }, | ||
| { | ||
| "type": "null" | ||
| } | ||
| ], | ||
| "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.", | ||
| "title": "X-Api-Key" | ||
| }, | ||
| "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings." | ||
| } | ||
| ], | ||
| "responses": { | ||
| "200": { | ||
| "description": "Successful Response", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/PortalSessionResponse" | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "422": { | ||
| "description": "Validation Error", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/HTTPValidationError" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "/api/v1/billing/state": { | ||
| "get": { | ||
| "summary": "Get Organization Billing", | ||
| "operationId": "get_organization_billing_api_v1_billing_state_get", | ||
| "parameters": [ | ||
| { | ||
| "name": "x-api-key", | ||
| "in": "header", | ||
| "required": false, | ||
| "schema": { | ||
| "anyOf": [ | ||
| { | ||
| "type": "string" | ||
| }, | ||
| { | ||
| "type": "null" | ||
| } | ||
| ], | ||
| "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.", | ||
| "title": "X-Api-Key" | ||
| }, | ||
| "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings." | ||
| } | ||
| ], | ||
| "responses": { | ||
| "200": { | ||
| "description": "Successful Response", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "anyOf": [ | ||
| { | ||
| "$ref": "#/components/schemas/BillingStateResponse" | ||
| }, | ||
| { | ||
| "type": "null" | ||
| } | ||
| ], | ||
| "title": "Response Get Organization Billing Api V1 Billing State Get" | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "422": { | ||
| "description": "Validation Error", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/HTTPValidationError" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "/api/v1/billing/change-tier": { | ||
| "post": { | ||
| "summary": "Change Tier", | ||
| "description": "Change the subscription tier (upgrade or downgrade).\n\nThis swaps the tier price while keeping metered items unchanged.\nStripe will fire a customer.subscription.updated webhook which\nupdates the billing state automatically.", | ||
| "operationId": "change_tier_api_v1_billing_change_tier_post", | ||
| "parameters": [ | ||
| { | ||
| "name": "x-api-key", | ||
| "in": "header", | ||
| "required": false, | ||
| "schema": { | ||
| "anyOf": [ | ||
| { | ||
| "type": "string" | ||
| }, | ||
| { | ||
| "type": "null" | ||
| } | ||
| ], | ||
| "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.", | ||
| "title": "X-Api-Key" | ||
| }, | ||
| "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings." | ||
| } | ||
| ], | ||
| "requestBody": { | ||
| "required": true, | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/ChangeTierRequest" | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "responses": { | ||
| "200": { | ||
| "description": "Successful Response", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/ChangeTierResponse" | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "422": { | ||
| "description": "Validation Error", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/HTTPValidationError" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, let's check the actual paths in the billing endpoints section
cd fern/openapi
head -c 500000 skyvern_openapi.json | tail -c 200000 | grep -A 5 '"/api/v1/billing' | head -50Repository: Skyvern-AI/skyvern
Length of output: 44
🏁 Script executed:
# Check various endpoint patterns
rg '"/[a-z]+' fern/openapi/skyvern_openapi.json | head -30Repository: Skyvern-AI/skyvern
Length of output: 1099
🏁 Script executed:
# Look specifically at the checkout endpoint to see all its details
rg -A 20 'create_checkout_session' fern/openapi/skyvern_openapi.json | head -50Repository: Skyvern-AI/skyvern
Length of output: 797
🏁 Script executed:
# Check if there are any 400 responses defined elsewhere in the spec
rg '"400"' fern/openapi/skyvern_openapi.json | head -20Repository: Skyvern-AI/skyvern
Length of output: 137
🏁 Script executed:
# Get the exact responses section for checkout
rg -A 40 '"create_checkout_session_api_v1_billing_checkout_post"' fern/openapi/skyvern_openapi.json | grep -A 30 '"responses"'Repository: Skyvern-AI/skyvern
Length of output: 363
🏁 Script executed:
# Find which endpoints have 400 responses
rg -B 10 '"400"' fern/openapi/skyvern_openapi.json | grep -E '(operationId|"400")' | head -40Repository: Skyvern-AI/skyvern
Length of output: 137
🏁 Script executed:
# Check all billing endpoints' responses
rg -A 45 'billing' fern/openapi/skyvern_openapi.json | grep -E '(operationId|"responses"|"200"|"400"|"422")' | head -50Repository: Skyvern-AI/skyvern
Length of output: 605
🏁 Script executed:
# Verify the exact description text for checkout
rg -A 5 'Create Checkout Session' fern/openapi/skyvern_openapi.json | head -10Repository: Skyvern-AI/skyvern
Length of output: 605
🏁 Script executed:
# Check if the description mentions the 400 error
rg -B 3 -A 8 '"Create Checkout Session"' fern/openapi/skyvern_openapi.json | head -20Repository: Skyvern-AI/skyvern
Length of output: 745
Add 400 response to checkout endpoint and verify path prefix consistency
The create_checkout_session endpoint description explicitly states "Returns 400 if org already has an active subscription (use portal instead)", but the responses section only declares 200 and 422. This spec/behavior mismatch will cause client generators to ignore the documented 400 error. Add the 400 response to align with the description:
"400": {
"description": "Org already has an active subscription; use portal instead."
}Additionally, all existing public endpoints follow the /v1/... pattern (e.g., /v1/run/tasks, /v1/workflows), but these new billing endpoints use /api/v1/billing/.... Verify this path prefix is correct for the live API; if it should be /v1/billing/... instead, update to match the established convention.
🤖 Prompt for AI Agents
In @fern/openapi/skyvern_openapi.json around lines 2953 - 3175, The OpenAPI spec
for create_checkout_session_api_v1_billing_checkout_post is missing the
documented 400 response: add a "400" responses entry with description "Org
already has an active subscription; use portal instead." to the
"/api/v1/billing/checkout" POST responses so client generators include it. Also
verify the path prefix consistency for all billing endpoints (currently
"/api/v1/billing/...") against the project's public API convention (e.g.,
"/v1/..."); if the intended prefix is "/v1/billing/..." rename the paths and
update the operationId tokens accordingly (e.g.,
create_checkout_session_api_v1_billing_checkout_post → adjust to match the new
path).
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Update API specifications by running fern api update.
📋 This PR updates API specifications using the
fern api updatecommand, ensuring the API documentation and schema definitions are synchronized with the latest changes. This appears to be a routine maintenance update to keep API specifications current and accurate.🔍 Detailed Analysis
Key Changes
Technical Implementation
flowchart TD A[Developer runs 'fern api update'] --> B[Fern analyzes current API] B --> C[Updates specification files] C --> D[Generates updated documentation] D --> E[Commits changes to repository] E --> F[Creates Pull Request]Impact
Limitations
Created with Palmier
Important
Update API specifications to include new billing endpoints and schemas, and update proxy location descriptions.
/api/v1/billing/checkoutfor creating Stripe Checkout Sessions./api/v1/billing/portalfor creating Stripe Customer Portal sessions./api/v1/billing/statefor retrieving organization billing state./api/v1/billing/change-tierfor changing subscription tiers.BillingStateResponse,ChangeTierRequest,ChangeTierResponse,CheckoutSessionResponse,CheckoutSubscriptionRequest,PortalSessionResponse, andPlanTier.RESIDENTIAL_PHand mark certain US locations as deprecated.This description was created by
for 6862abc. You can customize this summary. It will automatically update as commits are pushed.
Summary by CodeRabbit
Release Notes
✏️ Tip: You can customize this high-level summary in your review settings.