dbt-labs / dbt-labs/dbt-cloud-openapi-spec

v3 OpenAPI: create endpoints return 201 while spec only documents 200 (breaks generated clients)

Open
#78 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
12
Forks
10
PR merge metrics
No merged PRs in 30d

Description

Several dbt Cloud v3 create endpoints return 201 Created on success, but the OpenAPI spec only documents 200 as a successful response. Generated clients that strictly validate responses against the OpenAPI description then treat a successful call as an “unexpected status” and fail to deserialize the body.

This is forcing users to manually patch their generated clients or globally relax response validation.

**One concrete example from a customer:**
Method: `POST`
Path: `/api/v3/accounts/{account_id}/projects/{project_id}/repositories/`
Operation: Create Repository

Request body (simplified)
```
{
"account_id": 70471823534209,
"project_id": 70471823557666,
"state": 1,
"gitlab_project_id": "79781265",
"remote_url": "AgileFactory/Witboost.Mesh/mesh.repository/organization/employees/dbt-test-project"
}
```
Actual response from live API
- Note the status.code: 201 and HTTP status code 201

```
{
"status": {
"code": 201,
"is_success": true,
"user_message": "Success!",
"developer_message": ""
},
"data": {
"id": 70471823471018,
"account_id": 70471823534209,
"project_id": 70471823557666,
"full_name": "AgileFactory/Witboost.Mesh/mesh.repository/organization/employees/dbt-test-project",
"remote_url": "AgileFactory/Witboost.Mesh/mesh.repository/organization/employees/dbt-test-project",
"remote_backend": "gitlab",
"git_clone_strategy": "deploy_token",
"deploy_key_id": 70471823475545,
"repository_credentials_id": null,
"github_installation_id": null,
"github_webhook_id": null,
"pull_request_url_template": "https://gitlab.com/AgileFactory/Witboost.Mesh/mesh.repository/organization/employees/dbt-test-project/-/merge_requests/new?merge_request%5Bsource_branch%5D={{source}}&merge_request%5Btarget_branch%5D={{destination}}",
"state": 1,
"private_link_endpoint_id": null,
"git_provider_id": null,
"github_repo": null,
"name": "dbt-test-project",
"web_url": "https://gitlab.com/AgileFactory/Witboost.Mesh/mesh.repository/organization/employees/dbt-test-project",
"created_at": "2026-02-25 15:55:42.049199+00:00",
"updated_at": "2026-02-25 15:55:42.049212+00:00",
"deploy_key": {
"account_id": 70471823534209,
"public_key": "ssh-rsa AAAA... (truncated)"
}
},
"extra": {},
"error_code": null
}
```
**Expected behavior**
For each v3 create endpoint that returns 201 in practice, the OpenAPI spec should:
1. Declare 201 (and any other actually used success codes) as valid success responses alongside 200 (if applicable).
2. Reuse the correct response schema for the 201 case (the standard status + data envelope).
So a generated client can:
- Treat 201 as a valid, expected success status, and
- Correctly deserialize the response body without manual patches.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by locating the OpenAPI definitions for POST /api/v3/accounts/{account_id}/projects/{project_id}/repositories/ and the other v3 create endpoints. Compare their documented success responses with the live 201 behavior described here, then verify that each 201 response uses the standard status + data envelope and that generated-client response validation succeeds.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi
Domain
api
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.