Update API specifications with fern api update #4412
Closed
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
WalkthroughThe OpenAPI schema adds comprehensive billing functionality with four new endpoints (checkout, portal, state, change-tier), introduces seven new billing-related schemas, extends existing response types with browser and run step metadata, and expands the proxy location options with Philippines support. Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant Billing API
participant Payment Provider
participant Database
rect rgb(200, 220, 240)
Note over Client,Database: Checkout Flow
Client->>Billing API: POST /api/v1/billing/checkout<br/>(CheckoutSubscriptionRequest)
Billing API->>Payment Provider: Create checkout session
Payment Provider-->>Billing API: Session ID & URL
Billing API->>Database: Store session metadata
Billing API-->>Client: CheckoutSessionResponse
end
rect rgb(220, 240, 200)
Note over Client,Database: Portal Flow
Client->>Billing API: POST /api/v1/billing/portal
Billing API->>Payment Provider: Create portal session
Payment Provider-->>Billing API: Portal URL
Billing API-->>Client: PortalSessionResponse
end
rect rgb(240, 220, 200)
Note over Client,Database: Change Tier Flow
Client->>Billing API: POST /api/v1/billing/change-tier<br/>(ChangeTierRequest)
Billing API->>Database: Validate current tier & new PlanTier
Database-->>Billing API: Tier validation result
Billing API->>Payment Provider: Update subscription tier
Payment Provider-->>Billing API: Confirmation
Billing API->>Database: Persist new tier
Billing API-->>Client: ChangeTierResponse
end
sequenceDiagram
participant Client
participant Billing State API
participant Database
rect rgb(240, 240, 220)
Note over Client,Database: Retrieve Billing State
Client->>Billing State API: GET /api/v1/billing/state
Billing State API->>Database: Query current billing state
Database-->>Billing State API: BillingStateResponse data
Billing State API-->>Client: BillingStateResponse
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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.
Caution
Changes requested ❌
Reviewed everything up to 9fd9720 in 2 minutes and 31 seconds. Click for details.
- Reviewed
563lines of code in1files - Skipped
0files when reviewing. - Skipped posting
3draft 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:2953
- Draft comment:
The 'x-api-key' header parameter is duplicated in multiple endpoints. Consider extracting it as a reusable component to reduce repetition. - 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 refactor suggestion, which according to the rules can be good if actionable and clear. The suggestion is clear and actionable - extract the x-api-key parameter into the components section and reference it. However, I need to consider: 1) This is an OpenAPI JSON file that might be auto-generated from code, in which case manual edits would be overwritten. 2) The duplication already exists in the file (likely in other endpoints not shown in the diff), so this isn't introducing new technical debt, just continuing an existing pattern. 3) The comment is about code that was added in this PR (the new billing endpoints), so it is about changes. 4) While the suggestion is valid, it's not critical - the duplication doesn't cause functional issues. This OpenAPI file is likely auto-generated from Python code (given the operationId format like "create_checkout_session_api_v1_billing_checkout_post"), so manual edits to extract common parameters might be overwritten. Also, if this pattern already exists throughout the file, singling out these new endpoints seems inconsistent unless the entire file is refactored. The comment is technically correct and the suggestion is valid for OpenAPI best practices. However, given that this appears to be an auto-generated file and the duplication pattern likely exists throughout the entire specification (not just in the new endpoints), this comment may not be actionable without broader changes to how the OpenAPI spec is generated. The PR author likely doesn't manually edit this file. This comment should be deleted. While the suggestion is technically valid, the OpenAPI file appears to be auto-generated (based on the operation ID naming convention), making manual refactoring impractical. Additionally, if this duplication pattern exists throughout the file, addressing it only for these new endpoints would be inconsistent without a broader refactoring effort.
2. fern/openapi/skyvern_openapi.json:5332
- Draft comment:
In ChangeTierResponse, the 'tier' property is defined as a generic string. For consistency with ChangeTierRequest (which references PlanTier), consider referencing the PlanTier enum instead. - 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:5548
- Draft comment:
The 'browser_type' property is added in multiple schemas with identical definitions. If they represent the same concept, consider consolidating them into a single reusable schema for consistency. - Reason this comment was not posted:
Comment looked like it was already resolved.
Workflow ID: wflow_SKIgXsAvN0zbu7Zn
You can customize 
| "/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).", |
Contributor
There was a problem hiding this comment.
The /api/v1/billing/checkout endpoint description mentions returning a 400 error if the organization already has an active subscription, but no 400 response is defined. Please update either the description or add a 400 response.
![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
create_checkout_session_api_v1_billing_checkout_post operation documents a 400
behavior but lacks a 400 response entry—add a "400" response object (e.g.,
description and application/json schema or a reference to an existing error
schema) under the "/api/v1/billing/checkout" POST responses so generated
clients/docs include it; and change the ChangeTierResponse.tier field from a
plain "string" to use $ref: "#/components/schemas/PlanTier" so it matches
ChangeTierRequest.tier and provides strong typing. Apply the same 400-response
addition and PlanTier ref fix to other duplicated billing endpoint/schema
instances noted in the review.
🧹 Nitpick comments (1)
fern/openapi/skyvern_openapi.json (1)
5548-5557:BrowserSessionResponse.browser_typeis well-typed; consider clarifying default semanticsThe nullable
browser_typereferencingPersistentBrowserTypeis sound and keeps backwards compatibility. If there is a de-facto default (e.g., current browser engine whennull), consider documenting that so SDK consumers know what to assume when the field is absent/null.
📜 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). (2)
- GitHub Check: Run tests and pre-commit hooks
- GitHub Check: Analyze (python)
🔇 Additional comments (3)
fern/openapi/skyvern_openapi.json (3)
3504-3514: Newscreenshot_artifact_idonActionlooks consistentOptional
screenshot_artifact_idmatches other *_id fields (string or null) and is not added torequired, so it’s backward compatible for existing clients.
6341-6377: Proxy geotargeting +RESIDENTIAL_PHwiring looks correct
RESIDENTIAL_PHis added toProxyLocationand consistently referenced in the proxy_location descriptions forCreateBrowserSessionRequest,TaskRunRequest, andWorkflowRunRequest. All three descriptions stay in sync and remain backwards compatible (field is still optional / accepts previous enum values).Also applies to: 12016-12045, 13549-13568, 17478-17497
14014-14025:step_counton run responses is backwards compatible and usefulAdding nullable
step_counttoTaskRunResponseandWorkflowRunResponseis safe (not inrequired) and gives clients a straightforward way to introspect run complexity. No schema issues spotted.Also applies to: 17882-17893
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.
Billing endpoints/schemas generally solid; a couple of spec nits
- The
/api/v1/billing/checkoutdescription says “Returns 400 if org already has an active subscription (use portal instead)” but the response section only documents200and422. Consider explicitly adding a400response so generated clients and docs reflect the behavior. ChangeTierRequest.tieris aPlanTierenum, butChangeTierResponse.tieris a plainstring. If the response is intended to echo aPlanTier, using$ref: "#/components/schemas/PlanTier"would give SDKs stronger typing and symmetry between request/response.
Also applies to: 4616-4705, 5670-5727, 11907-11924, 11925-11937
🤖 Prompt for AI Agents
In @fern/openapi/skyvern_openapi.json around lines 2953 - 3175, The
create_checkout_session_api_v1_billing_checkout_post operation documents a 400
behavior but lacks a 400 response entry—add a "400" response object (e.g.,
description and application/json schema or a reference to an existing error
schema) under the "/api/v1/billing/checkout" POST responses so generated
clients/docs include it; and change the ChangeTierResponse.tier field from a
plain "string" to use $ref: "#/components/schemas/PlanTier" so it matches
ChangeTierRequest.tier and provides strong typing. Apply the same 400-response
addition and PlanTier ref fix to other duplicated billing endpoint/schema
instances noted in the review.
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 by running the
fern api updatecommand to synchronize the project's API definitions with the latest schema changes. The update ensures that the API documentation and generated code remain consistent with current specifications.🔍 Detailed Analysis
Key Changes
Technical Implementation
flowchart TD A[Fern API Update Command] --> B[Schema Validation] B --> C[Specification Files Updated] C --> D[Generated Code Refresh] D --> E[Documentation Sync] E --> F[API Consistency Maintained]Impact
Created with Palmier
Important
Update API specifications with new billing endpoints and schemas, and update geographic proxy options.
/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, andCheckoutSubscriptionRequest.PersistentBrowserTypeandPlanTierenums.RESIDENTIAL_PHand deprecated some US state options.This description was created by
for 9fd9720. You can customize this summary. It will automatically update as commits are pushed.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.