dbt-labs / dbt-labs/dbt-cloud-openapi-spec
v3 OpenAPI: create endpoints return 201 while spec only documents 200 (breaks generated clients)
- 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