feat:Mark OpenAPI operations/params deprecated and update Images image_url #282
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
WalkthroughOpenAPI spec updated to mark multiple operations and parameters as deprecated, including ChatConnector-related and search_queries_only. Certain responses include deprecated: true. Sample snippets for Images now annotate image_url to accept base64 data URIs or web URLs. No runtime or control-flow changes. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests
Tip 👮 Agentic pre-merge checks are now available in preview!Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.
Please see the documentation for more information. Example: reviews:
pre_merge_checks:
custom_checks:
- name: "Undocumented Breaking Changes"
mode: "warning"
instructions: |
Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).Please share your feedback with us on this Discord post. 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 |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
coderabbitai
bot
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (6)
src/libs/Cohere/openapi.yaml (6)
168-174: Good: explicit deprecation on search_queries_only. Add guidance.Marking the property deprecated is fine. Add a deprecation rationale and a replacement hint (e.g., x-deprecation-reason, x-replaced-by) so SDKs/docs can surface migration paths.
If you have a replacement, append:
x-deprecation-reason: "Explain why." x-replaced-by: "new_parameter_name"
1128-1134: Same as above: deprecation is fine; add rationale/sunset.Run the same lint as in the prior comment.
1198-1204: Same pattern—looks good; add deprecation metadata.Confirm lint passes and that operationId remains stable for SDKs.
1271-1277: OK to deprecate; communicate replacement and timelines.Add:
x-deprecation-reason: "…" x-sunset-date: "2026-03-31"
1501-1507: Deprecation OK; consider 410 plan post-sunset.Plan to flip to 410 Gone after the sunset date.
6623-6629: LGTM; ensure monitoring/alerts for residual traffic.Add alerts to track traffic to deprecated operation before removal.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (21)
src/libs/Cohere/Generated/Cohere.CohereClient.Chat.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.CohereClient.Classify.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.CohereClient.Generate.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.CohereClient.Summarize.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ConnectorsClient.CreateConnector.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ConnectorsClient.DeleteConnector.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ConnectorsClient.GetConnector.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ConnectorsClient.ListConnectors.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ConnectorsClient.OAuthAuthorizeConnector.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ConnectorsClient.UpdateConnector.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ICohereClient.Chat.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ICohereClient.Classify.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ICohereClient.Generate.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ICohereClient.Summarize.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.IConnectorsClient.CreateConnector.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.IConnectorsClient.DeleteConnector.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.IConnectorsClient.GetConnector.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.IConnectorsClient.ListConnectors.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.IConnectorsClient.OAuthAuthorizeConnector.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.IConnectorsClient.UpdateConnector.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ChatRequest.g.csis excluded by!**/generated/**
📒 Files selected for processing (1)
src/libs/Cohere/openapi.yaml(12 hunks)
⏰ 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: Test / Build, test and publish
🔇 Additional comments (4)
src/libs/Cohere/openapi.yaml (4)
1343-1349: Operation marked deprecated—LGTM; check tags/docs sync.Ensure changelog/release notes reflect this endpoint’s deprecation.
1421-1427: Consistent deprecation—nice. Validate no breaking SDK regen.If codegen is automated, gate SDK release with a deprecation notice rather than removal.
7178-7184: Deprecation consistent—verify SDKs treat as warn, not error.Some generators break on deprecated fields if configured strictly; ensure config is warning-only.
63-69: Fix invalid $ref siblings and clarify deprecation target.Ran
npx -y @redocly/cli@latest lint src/libs/Cohere/openapi.yaml— validation failed (1 error, 20 warnings). Top error: Schema type mismatch at src/libs/Cohere/openapi.yaml:13949 (#/components/schemas/EmbedByTypeResponse/properties/embeddings/items). Resolve that validation error first; then address the $ref/deprecatedplacement below.Placing
description/deprecatedalongside$refunderitemsis illegal in OAS 3.0 and ambiguous in 3.1. If the intent is to deprecate the connectors parameter (not the item schema), movedeprecatedto the parameter/property level.Apply one of the following:
Option A — deprecate the field (preferred):
items: - $ref: '#/components/schemas/ChatConnector' - description: "Accepts …" - deprecated: true + $ref: '#/components/schemas/ChatConnector' + description: "Accepts …" +deprecated: true # move to the connectors parameter/property nodeOption B — keep on items but avoid $ref siblings:
items: - $ref: '#/components/schemas/ChatConnector' - description: "Accepts …" - deprecated: true + allOf: + - $ref: '#/components/schemas/ChatConnector' + description: "Accepts …" + deprecated: trueRun a validator again after fixes:
#!/bin/bash npx -y @redocly/cli@latest lint src/libs/Cohere/openapi.yaml
Comment on lines
1004
to
1010
| $ref: '#/components/responses/ServiceUnavailable' | ||
| '504': | ||
| $ref: '#/components/responses/GatewayTimeout' | ||
| deprecated: true | ||
| x-fern-audiences: | ||
| - public | ||
| x-fern-examples: |
There was a problem hiding this comment.
🧩 Analysis chain
Operation deprecation OK; confirm indentation and surface migration.
deprecated: true at the operation level is correct. Ensure indentation places it as a sibling of responses, not inside it. Add x-deprecation-reason/x-sunset-date for docs.
🏁 Script executed:
#!/bin/bash
npx -y @redocly/cli@latest lint src/libs/Cohere/openapi.yaml
rg -nC2 -P '^\s*deprecated:\s*true\s*$' src/libs/Cohere/openapi.yamlLength of output: 11747
Fix blocking OpenAPI lint errors; confirm deprecation placement & add deprecation metadata.
- Blocking error: src/libs/Cohere/openapi.yaml:13949 — components/schemas/EmbedByTypeResponse/properties/embeddings/items: Schema type mismatch ('object' type should not contain 'items'). Fix this schema first.
- Resolve undefined required-property warnings (examples): CreateConnectorOAuth required keys missing at 13572–13575 (clientId, clientSecret, authorizeUrl, tokenUrl); api_version required but undefined at 13943 and 15255; address other linter warnings.
- Deprecation: operation-level deprecated: true is present (examples ~lines 66, 171, 862). Ensure deprecated: true is a sibling of responses (not nested) and add x-deprecation-reason and x-sunset-date on deprecated operations for documentation.
🤖 Prompt for AI Agents
In src/libs/Cohere/openapi.yaml around lines 1004 to 1010, fix multiple OpenAPI
linter errors: change components/schemas/EmbedByTypeResponse so that the
embeddings property uses a valid schema (if embeddings is an array declare type:
array with items: {type: object/...} or if it is an object remove items and use
properties/type: object), ensure every name in CreateConnectorOAuth's required
array (clientId, clientSecret, authorizeUrl, tokenUrl) actually exists under its
properties (add those property definitions or remove them from required), define
the missing api_version property where it's marked required (or remove it from
required) at the noted locations, resolve any other undefined-required warnings
by adding matching property definitions, and move deprecated: true to be a
sibling of responses for operation-level deprecations and add
x-deprecation-reason and x-sunset-date metadata to those deprecated operations
to satisfy linting and documentation requirements.
Comment on lines
+8775
to
8787
| - code: "const { CohereClientV2 } = require('cohere-ai');\n\nconst cohere = new CohereClientV2({});\n\n(async () => {\n const response = await cohere.chat({\n model: 'command-a-vision-07-2025',\n messages: [\n {\n role: 'user',\n content: [\n { type: 'text', text: 'Describe the logo!' },\n {\n type: 'image_url',\n imageUrl: {\n // Can be either a base64 data URI or a web URL.\n url: 'https://cohere.com/favicon-32x32.png',\n detail: 'auto',\n },\n },\n ],\n },\n ],\n });\n console.log(response.message.content[0].text);\n})();\n" | ||
| name: Images | ||
| sdk: typescript | ||
| - code: "import cohere\n\nco = cohere.ClientV2()\n\nresponse = co.chat(\n model=\"command-a-vision-07-2025\",\n messages=[\n {\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": \"Describe the logo!\"\n },\n {\n \"type\": \"image_url\",\n \"image_url\": {\n \"url\": \"https://cohere.com/favicon-32x32.png\",\n \"detail\": \"auto\"\n }\n }\n ]\n \n }\n ]\n)\n\nprint(response)" | ||
| - code: "import cohere\n\nco = cohere.ClientV2()\n\nresponse = co.chat(\n model=\"command-a-vision-07-2025\",\n messages=[\n {\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": \"Describe the logo!\"\n },\n {\n \"type\": \"image_url\",\n \"image_url\": {\n # Can be either a base64 data URI or a web URL.\n \"url\": \"https://cohere.com/favicon-32x32.png\",\n \"detail\": \"auto\"\n }\n }\n ]\n \n }\n ]\n)\n\nprint(response)" | ||
| name: Images | ||
| sdk: python | ||
| - code: "/* (C)2024 */\npackage chatv2post;\n\nimport java.util.List;\n\nimport com.cohere.api.Cohere;\nimport com.cohere.api.resources.v2.requests.V2ChatRequest;\nimport com.cohere.api.types.ChatMessageV2;\nimport com.cohere.api.types.ChatResponse;\nimport com.cohere.api.types.Content;\nimport com.cohere.api.types.ImageContent;\nimport com.cohere.api.types.ImageUrl;\nimport com.cohere.api.types.TextContent;\nimport com.cohere.api.types.UserMessage;\nimport com.cohere.api.types.UserMessageContent;\n\npublic class Image {\n\n public static void main(String[] args) {\n Cohere cohere = Cohere.builder().clientName(\"snippet\").build();\n\n ChatResponse response\n = cohere\n .v2()\n .chat(\n V2ChatRequest.builder()\n .model(\"command-a-vision-07-2025\")\n .messages(\n List.of(\n ChatMessageV2.user(\n UserMessage.builder()\n .content(\n UserMessageContent.of(\n List.of(\n Content.text(\n TextContent.builder()\n .text(\"Describe the logo!\")\n .build()),\n Content.imageUrl(\n ImageContent.builder()\n .imageUrl(\n ImageUrl.builder()\n .url(\n \"https://cohere.com/favicon-32x32.png\")\n .build())\n .build()))))\n .build())))\n .build());\n System.out.println(response);\n }\n}\n" | ||
| - code: "/* (C)2024 */\npackage chatv2post;\n\nimport java.util.List;\n\nimport com.cohere.api.Cohere;\nimport com.cohere.api.resources.v2.requests.V2ChatRequest;\nimport com.cohere.api.types.ChatMessageV2;\nimport com.cohere.api.types.ChatResponse;\nimport com.cohere.api.types.Content;\nimport com.cohere.api.types.ImageContent;\nimport com.cohere.api.types.ImageUrl;\nimport com.cohere.api.types.TextContent;\nimport com.cohere.api.types.UserMessage;\nimport com.cohere.api.types.UserMessageContent;\n\npublic class Image {\n\n public static void main(String[] args) {\n Cohere cohere = Cohere.builder().clientName(\"snippet\").build();\n\n ChatResponse response\n = cohere\n .v2()\n .chat(\n V2ChatRequest.builder()\n .model(\"command-a-vision-07-2025\")\n .messages(\n List.of(\n ChatMessageV2.user(\n UserMessage.builder()\n .content(\n UserMessageContent.of(\n List.of(\n Content.text(\n TextContent.builder()\n .text(\"Describe the logo!\")\n .build()),\n Content.imageUrl(\n ImageContent.builder()\n .imageUrl(\n ImageUrl.builder()\n // Can be either a base64 data URI or a web URL.\n .url(\n \"https://cohere.com/favicon-32x32.png\")\n .build())\n .build()))))\n .build())))\n .build());\n System.out.println(response);\n }\n}\n" | ||
| name: Images | ||
| sdk: java | ||
| - code: "package main\n\nimport (\n\t\"context\"\n\t\"log\"\n\t\"os\"\n\n\tcohere \"github.com/cohere-ai/cohere-go/v2\"\n\tclient \"github.com/cohere-ai/cohere-go/v2/client\"\n)\n\nfunc main() {\n\tco := client.NewClient(client.WithToken(os.Getenv(\"CO_API_KEY\")))\n\n\tresp, err := co.V2.Chat(\n\t\tcontext.TODO(),\n\t\t&cohere.V2ChatRequest{\n\t\t\tModel: \"command-a-03-2025\",\n\t\t\tMessages: cohere.ChatMessages{\n\t\t\t\t{\n\t\t\t\t\tRole: \"user\",\n\t\t\t\t\tUser: &cohere.UserMessageV2{Content: &cohere.UserMessageV2Content{\n\t\t\t\t\t\tContentList: []*cohere.Content{\n\t\t\t\t\t\t\t{Type: \"text\", Text: &cohere.ChatTextContent{Text: \"Describe the logo!\"}},\n\t\t\t\t\t\t\t{Type: \"image_url\", ImageUrl: &cohere.ImageContent{\n\t\t\t\t\t\t\t\tImageUrl: &cohere.ImageUrl{\n\t\t\t\t\t\t\t\t\tUrl: \"https://cohere.com/favicon-32x32.png\",\n\t\t\t\t\t\t\t\t\tDetail: cohere.ImageUrlDetailAuto.Ptr(),\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t}},\n\t\t\t\t\t\t}}},\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t)\n\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\tlog.Printf(\"%+v\", resp)\n}\n" | ||
| - code: "package main\n\nimport (\n\t\"context\"\n\t\"log\"\n\t\"os\"\n\n\tcohere \"github.com/cohere-ai/cohere-go/v2\"\n\tclient \"github.com/cohere-ai/cohere-go/v2/client\"\n)\n\nfunc main() {\n\tco := client.NewClient(client.WithToken(os.Getenv(\"CO_API_KEY\")))\n\n\tresp, err := co.V2.Chat(\n\t\tcontext.TODO(),\n\t\t&cohere.V2ChatRequest{\n\t\t\tModel: \"command-a-03-2025\",\n\t\t\tMessages: cohere.ChatMessages{\n\t\t\t\t{\n\t\t\t\t\tRole: \"user\",\n\t\t\t\t\tUser: &cohere.UserMessageV2{Content: &cohere.UserMessageV2Content{\n\t\t\t\t\t\tContentList: []*cohere.Content{\n\t\t\t\t\t\t\t{Type: \"text\", Text: &cohere.ChatTextContent{Text: \"Describe the logo!\"}},\n\t\t\t\t\t\t\t{Type: \"image_url\", ImageUrl: &cohere.ImageContent{\n\t\t\t\t\t\t\t\tImageUrl: &cohere.ImageUrl{\n\t\t\t\t\t\t\t\t\t// Can be either a base64 data URI or a web URL.\n\t\t\t\t\t\t\t\t\tUrl: \"https://cohere.com/favicon-32x32.png\",\n\t\t\t\t\t\t\t\t\tDetail: cohere.ImageUrlDetailAuto.Ptr(),\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t}},\n\t\t\t\t\t\t}}},\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t)\n\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\tlog.Printf(\"%+v\", resp)\n}\n" | ||
| name: Images | ||
| sdk: go | ||
| - code: "curl --request POST \\\n --url https://api.cohere.com/v2/chat \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --header \"Authorization: bearer $CO_API_KEY\" \\\n --data '{\n \"model\": \"command-a-vision-07-2025\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": \"Describe the logo!\"\n },\n {\n \"type\": \"image_url\",\n \"image_url\": {\n \"url\": \"https://cohere.com/favicon-32x32.png\",\n \"detail\": \"auto\"\n }\n }\n ]\n }\n ]\n }'\n" |
There was a problem hiding this comment.
🧩 Analysis chain
Sample updates: verify field casing and model consistency across SDKs.
- TS uses imageUrl under type: 'image_url'; Python/curl use image_url. Confirm SDK expects camelCase vs snake_case for the nested field.
- Models vary (command-a-vision-07-2025 vs command-a-03-2025). Consider aligning to one for clarity.
🌐 Web query:
For Cohere V2 SDKs, what is the correct field name for the image URL content in:
- Node/TS Content items (imageUrl vs image_url)?
- Python SDK (image_url)?
Do official docs provide a canonical sample?
💡 Result:
- Node/TypeScript content items: use image_url (snake_case), not imageUrl. [1][2]
- Python SDK: use image_url (snake_case). [1][3]
- Official canonical samples: yes — Cohere's docs (Chat API / Image Inputs) show the image content part as {"type":"image_url", "image_url": {"url": "..."} } (see Chat and Image Inputs pages). [1][2]
Sources:
[1] Cohere — Using Cohere's Models to Work with Image Inputs (examples showing "type":"image_url" and "image_url": {"url": ...}).
[2] Cohere — Chat API reference (chat message content examples use "image_url").
[3] Cohere — Embed / SDK docs and SDK repo (Python examples use "image_url").
Use snake_case "image_url" for image inputs and unify model id
Cohere docs/SDKs use image_url (snake_case) for Content items; canonical sample: {"type":"image_url","image_url":{"url":"..."}}.
- Replace any imageUrl keys in src/libs/Cohere/openapi.yaml (≈ lines 8775–8787) with image_url and update nested schemas/examples to match the canonical sample.
- Standardize the model identifier across the spec (choose and use either command-a-vision-07-2025 or command-a-03-2025) and update all references/examples.
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 by CodeRabbit
Deprecations
Documentation