diff --git a/src/resources/completions.ts b/src/resources/completions.ts
index b4d2629..6e06a8a 100644
--- a/src/resources/completions.ts
+++ b/src/resources/completions.ts
@@ -8,7 +8,15 @@ import { Stream } from '@anthropic-ai/sdk/streaming';
 
 export class Completions extends APIResource {
   /**
-   * Create a Text Completion
+   * [Legacy] Create a Text Completion.
+   *
+   * The Text Completions API is a legacy API. We recommend using the
+   * [Messages API](https://docs.anthropic.com/claude/reference/messages_post) going
+   * forward.
+   *
+   * Future models and features will not be compatible with Text Completions. See our
+   * [migration guide](https://docs.anthropic.com/claude/reference/migrating-from-text-completions-to-messages)
+   * for guidance in migrating from Text Completions to Messages.
    */
   create(body: CompletionCreateParamsNonStreaming, options?: Core.RequestOptions): APIPromise<Completion>;
   create(