From 61f098d3e54db1a7ed6e927cfd0a4b036ceb97c9 Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Sat, 25 Jul 2026 07:12:48 +0000
Subject: [PATCH 1/3] feat(api): api update

---
 .stats.yml                                |   4 +-
 src/Monitors/MonitorCreateParams.php      | 106 ++++++++++------------
 src/Monitors/MonitorNewResponse.php       |  24 ++++-
 src/ServiceContracts/MonitorsContract.php |  10 +-
 src/Services/MonitorsRawService.php       |   6 +-
 src/Services/MonitorsService.php          |  14 +--
 tests/Services/MonitorsTest.php           |   6 +-
 7 files changed, 92 insertions(+), 78 deletions(-)

diff --git a/.stats.yml b/.stats.yml
index 0ac1eb3..6da4682 100644
--- a/.stats.yml
+++ b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 32
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-242450ea46eb8c3e843fd6c4bf87e73192b5f62f6da697cd091d13c6aa7a991b.yml
-openapi_spec_hash: c1c561976de1abcacede71fd5ab9b3d9
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-2bf2b44f6593c44b2948683469bbb2b09cd8e90c97b12057fac6220cf0d2eee7.yml
+openapi_spec_hash: ae8b5109ec997cac8d3e6ec96040f6c8
 config_hash: 70e7e80b5e87f94981bee396c6cd41e8
diff --git a/src/Monitors/MonitorCreateParams.php b/src/Monitors/MonitorCreateParams.php
index 56eec6e..6786369 100644
--- a/src/Monitors/MonitorCreateParams.php
+++ b/src/Monitors/MonitorCreateParams.php
@@ -25,19 +25,19 @@
  *
  * @see ContextDev\Services\MonitorsService::create()
  *
- * @phpstan-import-type ChangeDetectionVariants from \ContextDev\Monitors\MonitorCreateParams\ChangeDetection
  * @phpstan-import-type TargetVariants from \ContextDev\Monitors\MonitorCreateParams\Target
+ * @phpstan-import-type ChangeDetectionVariants from \ContextDev\Monitors\MonitorCreateParams\ChangeDetection
+ * @phpstan-import-type TargetShape from \ContextDev\Monitors\MonitorCreateParams\Target
  * @phpstan-import-type ChangeDetectionShape from \ContextDev\Monitors\MonitorCreateParams\ChangeDetection
  * @phpstan-import-type ScheduleShape from \ContextDev\Monitors\MonitorCreateParams\Schedule
- * @phpstan-import-type TargetShape from \ContextDev\Monitors\MonitorCreateParams\Target
  * @phpstan-import-type WebhookShape from \ContextDev\Monitors\MonitorCreateParams\Webhook
  *
  * @phpstan-type MonitorCreateParamsShape = array{
- *   changeDetection: ChangeDetectionShape,
  *   name: string,
- *   schedule: Schedule|ScheduleShape,
  *   target: TargetShape,
+ *   changeDetection?: ChangeDetectionShape|null,
  *   mode?: null|Mode|value-of<Mode>,
+ *   schedule?: null|Schedule|ScheduleShape,
  *   tags?: list<string>|null,
  *   webhook?: null|Webhook|WebhookShape,
  * }
@@ -48,23 +48,9 @@ final class MonitorCreateParams implements BaseModel
     use SdkModel;
     use SdkParams;
 
-    /**
-     * Discriminated union describing how changes are detected.
-     *
-     * @var ChangeDetectionVariants $changeDetection
-     */
-    #[Required('change_detection', union: ChangeDetection::class)]
-    public MonitorsExactChangeDetection|MonitorsSemanticChangeDetection $changeDetection;
-
     #[Required]
     public string $name;
 
-    /**
-     * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. every 6 hours or every 2 days. The total interval (frequency × unit) must be between 10 minutes and 1 year.
-     */
-    #[Required]
-    public Schedule $schedule;
-
     /**
      * Discriminated union describing what the monitor watches.
      *
@@ -73,6 +59,14 @@ final class MonitorCreateParams implements BaseModel
     #[Required(union: Target::class)]
     public MonitorsPageTarget|MonitorsSitemapTarget|MonitorsExtractTarget $target;
 
+    /**
+     * Discriminated union describing how changes are detected.
+     *
+     * @var ChangeDetectionVariants|null $changeDetection
+     */
+    #[Optional('change_detection', union: ChangeDetection::class)]
+    public MonitorsExactChangeDetection|MonitorsSemanticChangeDetection|null $changeDetection;
+
     /**
      * Top-level monitor category. Always `web` today; the concrete behavior is described by `target` and `change_detection`.
      *
@@ -81,6 +75,12 @@ final class MonitorCreateParams implements BaseModel
     #[Optional(enum: Mode::class)]
     public ?string $mode;
 
+    /**
+     * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. every 6 hours or every 2 days. The total interval (frequency × unit) must be between 10 minutes and 1 year.
+     */
+    #[Optional]
+    public ?Schedule $schedule;
+
     /**
      * User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed.
      *
@@ -97,19 +97,13 @@ final class MonitorCreateParams implements BaseModel
      *
      * To enforce required parameters use
      * ```
-     * MonitorCreateParams::with(
-     *   changeDetection: ..., name: ..., schedule: ..., target: ...
-     * )
+     * MonitorCreateParams::with(name: ..., target: ...)
      * ```
      *
      * Otherwise ensure the following setters are called
      *
      * ```
-     * (new MonitorCreateParams)
-     *   ->withChangeDetection(...)
-     *   ->withName(...)
-     *   ->withSchedule(...)
-     *   ->withTarget(...)
+     * (new MonitorCreateParams)->withName(...)->withTarget(...)
      * ```
      */
     public function __construct()
@@ -122,50 +116,36 @@ public function __construct()
      *
      * You must use named parameters to construct any parameters with a default value.
      *
-     * @param ChangeDetectionShape $changeDetection
-     * @param Schedule|ScheduleShape $schedule
      * @param TargetShape $target
+     * @param ChangeDetectionShape|null $changeDetection
      * @param Mode|value-of<Mode>|null $mode
+     * @param Schedule|ScheduleShape|null $schedule
      * @param list<string>|null $tags
      * @param Webhook|WebhookShape|null $webhook
      */
     public static function with(
-        MonitorsExactChangeDetection|array|MonitorsSemanticChangeDetection $changeDetection,
         string $name,
-        Schedule|array $schedule,
         MonitorsPageTarget|array|MonitorsSitemapTarget|MonitorsExtractTarget $target,
+        MonitorsExactChangeDetection|array|MonitorsSemanticChangeDetection|null $changeDetection = null,
         Mode|string|null $mode = null,
+        Schedule|array|null $schedule = null,
         ?array $tags = null,
         Webhook|array|null $webhook = null,
     ): self {
         $self = new self;
 
-        $self['changeDetection'] = $changeDetection;
         $self['name'] = $name;
-        $self['schedule'] = $schedule;
         $self['target'] = $target;
 
+        null !== $changeDetection && $self['changeDetection'] = $changeDetection;
         null !== $mode && $self['mode'] = $mode;
+        null !== $schedule && $self['schedule'] = $schedule;
         null !== $tags && $self['tags'] = $tags;
         null !== $webhook && $self['webhook'] = $webhook;
 
         return $self;
     }
 
-    /**
-     * Discriminated union describing how changes are detected.
-     *
-     * @param ChangeDetectionShape $changeDetection
-     */
-    public function withChangeDetection(
-        MonitorsExactChangeDetection|array|MonitorsSemanticChangeDetection $changeDetection,
-    ): self {
-        $self = clone $this;
-        $self['changeDetection'] = $changeDetection;
-
-        return $self;
-    }
-
     public function withName(string $name): self
     {
         $self = clone $this;
@@ -175,28 +155,29 @@ public function withName(string $name): self
     }
 
     /**
-     * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. every 6 hours or every 2 days. The total interval (frequency × unit) must be between 10 minutes and 1 year.
+     * Discriminated union describing what the monitor watches.
      *
-     * @param Schedule|ScheduleShape $schedule
+     * @param TargetShape $target
      */
-    public function withSchedule(Schedule|array $schedule): self
-    {
+    public function withTarget(
+        MonitorsPageTarget|array|MonitorsSitemapTarget|MonitorsExtractTarget $target
+    ): self {
         $self = clone $this;
-        $self['schedule'] = $schedule;
+        $self['target'] = $target;
 
         return $self;
     }
 
     /**
-     * Discriminated union describing what the monitor watches.
+     * Discriminated union describing how changes are detected.
      *
-     * @param TargetShape $target
+     * @param ChangeDetectionShape $changeDetection
      */
-    public function withTarget(
-        MonitorsPageTarget|array|MonitorsSitemapTarget|MonitorsExtractTarget $target
+    public function withChangeDetection(
+        MonitorsExactChangeDetection|array|MonitorsSemanticChangeDetection $changeDetection,
     ): self {
         $self = clone $this;
-        $self['target'] = $target;
+        $self['changeDetection'] = $changeDetection;
 
         return $self;
     }
@@ -214,6 +195,19 @@ public function withMode(Mode|string $mode): self
         return $self;
     }
 
+    /**
+     * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. every 6 hours or every 2 days. The total interval (frequency × unit) must be between 10 minutes and 1 year.
+     *
+     * @param Schedule|ScheduleShape $schedule
+     */
+    public function withSchedule(Schedule|array $schedule): self
+    {
+        $self = clone $this;
+        $self['schedule'] = $schedule;
+
+        return $self;
+    }
+
     /**
      * User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed.
      *
diff --git a/src/Monitors/MonitorNewResponse.php b/src/Monitors/MonitorNewResponse.php
index d70d44e..809d822 100644
--- a/src/Monitors/MonitorNewResponse.php
+++ b/src/Monitors/MonitorNewResponse.php
@@ -26,7 +26,7 @@
 use ContextDev\Monitors\MonitorNewResponse\WebhookFailure;
 
 /**
- * A web monitor. `mode` is the constant `web`; behavior is described by `target` (page/sitemap/extract) and `change_detection` (exact/semantic).
+ * A newly created monitor plus `initial_run_id`, the id of the baseline run queued at creation.
  *
  * @phpstan-import-type ChangeDetectionVariants from \ContextDev\Monitors\MonitorNewResponse\ChangeDetection
  * @phpstan-import-type TargetVariants from \ContextDev\Monitors\MonitorNewResponse\Target
@@ -43,6 +43,7 @@
  *   id: string,
  *   changeDetection: ChangeDetectionShape,
  *   createdAt: \DateTimeInterface,
+ *   initialRunID: string|null,
  *   mode: Mode|value-of<Mode>,
  *   name: string,
  *   schedule: Schedule|ScheduleShape,
@@ -78,6 +79,12 @@ final class MonitorNewResponse implements BaseModel
     #[Required('created_at')]
     public \DateTimeInterface $createdAt;
 
+    /**
+     * The baseline run queued by this create call, or null if it could not be queued immediately (in which case the baseline runs on the next scheduled tick). Poll GET /monitors/{monitor_id}/runs/{run_id}.
+     */
+    #[Required('initial_run_id')]
+    public ?string $initialRunID;
+
     /**
      * Top-level monitor category. Always `web` today; the concrete behavior is described by `target` and `change_detection`.
      *
@@ -166,6 +173,7 @@ final class MonitorNewResponse implements BaseModel
      *   id: ...,
      *   changeDetection: ...,
      *   createdAt: ...,
+     *   initialRunID: ...,
      *   mode: ...,
      *   name: ...,
      *   schedule: ...,
@@ -182,6 +190,7 @@ final class MonitorNewResponse implements BaseModel
      *   ->withID(...)
      *   ->withChangeDetection(...)
      *   ->withCreatedAt(...)
+     *   ->withInitialRunID(...)
      *   ->withMode(...)
      *   ->withName(...)
      *   ->withSchedule(...)
@@ -215,6 +224,7 @@ public static function with(
         string $id,
         MonitorsExactChangeDetection|array|MonitorsSemanticChangeDetection $changeDetection,
         \DateTimeInterface $createdAt,
+        ?string $initialRunID,
         Mode|string $mode,
         string $name,
         Schedule|array $schedule,
@@ -235,6 +245,7 @@ public static function with(
         $self['id'] = $id;
         $self['changeDetection'] = $changeDetection;
         $self['createdAt'] = $createdAt;
+        $self['initialRunID'] = $initialRunID;
         $self['mode'] = $mode;
         $self['name'] = $name;
         $self['schedule'] = $schedule;
@@ -284,6 +295,17 @@ public function withCreatedAt(\DateTimeInterface $createdAt): self
         return $self;
     }
 
+    /**
+     * The baseline run queued by this create call, or null if it could not be queued immediately (in which case the baseline runs on the next scheduled tick). Poll GET /monitors/{monitor_id}/runs/{run_id}.
+     */
+    public function withInitialRunID(?string $initialRunID): self
+    {
+        $self = clone $this;
+        $self['initialRunID'] = $initialRunID;
+
+        return $self;
+    }
+
     /**
      * Top-level monitor category. Always `web` today; the concrete behavior is described by `target` and `change_detection`.
      *
diff --git a/src/ServiceContracts/MonitorsContract.php b/src/ServiceContracts/MonitorsContract.php
index 6a3ae2e..5f9c1fd 100644
--- a/src/ServiceContracts/MonitorsContract.php
+++ b/src/ServiceContracts/MonitorsContract.php
@@ -34,9 +34,9 @@
 use ContextDev\RequestOptions;
 
 /**
+ * @phpstan-import-type TargetShape from \ContextDev\Monitors\MonitorCreateParams\Target
  * @phpstan-import-type ChangeDetectionShape from \ContextDev\Monitors\MonitorCreateParams\ChangeDetection
  * @phpstan-import-type ScheduleShape from \ContextDev\Monitors\MonitorCreateParams\Schedule
- * @phpstan-import-type TargetShape from \ContextDev\Monitors\MonitorCreateParams\Target
  * @phpstan-import-type WebhookShape from \ContextDev\Monitors\MonitorCreateParams\Webhook
  * @phpstan-import-type ChangeDetectionShape from \ContextDev\Monitors\MonitorUpdateParams\ChangeDetection as ChangeDetectionShape1
  * @phpstan-import-type ScheduleShape from \ContextDev\Monitors\MonitorUpdateParams\Schedule as ScheduleShape1
@@ -49,10 +49,10 @@ interface MonitorsContract
     /**
      * @api
      *
-     * @param ChangeDetectionShape $changeDetection discriminated union describing how changes are detected
-     * @param Schedule|ScheduleShape $schedule Run the monitor on a fixed interval defined by a frequency and a unit, e.g. every 6 hours or every 2 days. The total interval (frequency × unit) must be between 10 minutes and 1 year.
      * @param TargetShape $target discriminated union describing what the monitor watches
+     * @param ChangeDetectionShape $changeDetection discriminated union describing how changes are detected
      * @param Mode|value-of<Mode> $mode Top-level monitor category. Always `web` today; the concrete behavior is described by `target` and `change_detection`.
+     * @param Schedule|ScheduleShape $schedule Run the monitor on a fixed interval defined by a frequency and a unit, e.g. every 6 hours or every 2 days. The total interval (frequency × unit) must be between 10 minutes and 1 year.
      * @param list<string> $tags User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed.
      * @param Webhook|WebhookShape|null $webhook
      * @param RequestOpts|null $requestOptions
@@ -60,11 +60,11 @@ interface MonitorsContract
      * @throws APIException
      */
     public function create(
-        MonitorsExactChangeDetection|array|MonitorsSemanticChangeDetection $changeDetection,
         string $name,
-        Schedule|array $schedule,
         MonitorsPageTarget|array|MonitorsSitemapTarget|MonitorsExtractTarget $target,
+        MonitorsExactChangeDetection|array|MonitorsSemanticChangeDetection|null $changeDetection = null,
         Mode|string|null $mode = null,
+        Schedule|array|null $schedule = null,
         ?array $tags = null,
         Webhook|array|null $webhook = null,
         RequestOptions|array|null $requestOptions = null,
diff --git a/src/Services/MonitorsRawService.php b/src/Services/MonitorsRawService.php
index 365560f..ae9e8ed 100644
--- a/src/Services/MonitorsRawService.php
+++ b/src/Services/MonitorsRawService.php
@@ -43,9 +43,9 @@
 /**
  * Monitor pages, sitemaps, and extracted website data for exact or semantic changes. Webhook payloads are documented by the MonitorsChangeDetectedWebhookPayload and MonitorsRunCompletedWebhookPayload schemas.
  *
+ * @phpstan-import-type TargetShape from \ContextDev\Monitors\MonitorCreateParams\Target
  * @phpstan-import-type ChangeDetectionShape from \ContextDev\Monitors\MonitorCreateParams\ChangeDetection
  * @phpstan-import-type ScheduleShape from \ContextDev\Monitors\MonitorCreateParams\Schedule
- * @phpstan-import-type TargetShape from \ContextDev\Monitors\MonitorCreateParams\Target
  * @phpstan-import-type WebhookShape from \ContextDev\Monitors\MonitorCreateParams\Webhook
  * @phpstan-import-type ChangeDetectionShape from \ContextDev\Monitors\MonitorUpdateParams\ChangeDetection as ChangeDetectionShape1
  * @phpstan-import-type ScheduleShape from \ContextDev\Monitors\MonitorUpdateParams\Schedule as ScheduleShape1
@@ -67,11 +67,11 @@ public function __construct(private Client $client) {}
      * Creates a monitor. The request body is a union of the supported target/change detection combinations. The monitor runs immediately after creation to create its initial baseline.
      *
      * @param array{
-     *   changeDetection: ChangeDetectionShape,
      *   name: string,
-     *   schedule: Schedule|ScheduleShape,
      *   target: TargetShape,
+     *   changeDetection?: ChangeDetectionShape,
      *   mode?: Mode|value-of<Mode>,
+     *   schedule?: Schedule|ScheduleShape,
      *   tags?: list<string>,
      *   webhook?: Webhook|WebhookShape|null,
      * }|MonitorCreateParams $params
diff --git a/src/Services/MonitorsService.php b/src/Services/MonitorsService.php
index 0ed99c1..e8c8926 100644
--- a/src/Services/MonitorsService.php
+++ b/src/Services/MonitorsService.php
@@ -39,9 +39,9 @@
 /**
  * Monitor pages, sitemaps, and extracted website data for exact or semantic changes. Webhook payloads are documented by the MonitorsChangeDetectedWebhookPayload and MonitorsRunCompletedWebhookPayload schemas.
  *
+ * @phpstan-import-type TargetShape from \ContextDev\Monitors\MonitorCreateParams\Target
  * @phpstan-import-type ChangeDetectionShape from \ContextDev\Monitors\MonitorCreateParams\ChangeDetection
  * @phpstan-import-type ScheduleShape from \ContextDev\Monitors\MonitorCreateParams\Schedule
- * @phpstan-import-type TargetShape from \ContextDev\Monitors\MonitorCreateParams\Target
  * @phpstan-import-type WebhookShape from \ContextDev\Monitors\MonitorCreateParams\Webhook
  * @phpstan-import-type ChangeDetectionShape from \ContextDev\Monitors\MonitorUpdateParams\ChangeDetection as ChangeDetectionShape1
  * @phpstan-import-type ScheduleShape from \ContextDev\Monitors\MonitorUpdateParams\Schedule as ScheduleShape1
@@ -69,10 +69,10 @@ public function __construct(private Client $client)
      *
      * Creates a monitor. The request body is a union of the supported target/change detection combinations. The monitor runs immediately after creation to create its initial baseline.
      *
-     * @param ChangeDetectionShape $changeDetection discriminated union describing how changes are detected
-     * @param Schedule|ScheduleShape $schedule Run the monitor on a fixed interval defined by a frequency and a unit, e.g. every 6 hours or every 2 days. The total interval (frequency × unit) must be between 10 minutes and 1 year.
      * @param TargetShape $target discriminated union describing what the monitor watches
+     * @param ChangeDetectionShape $changeDetection discriminated union describing how changes are detected
      * @param Mode|value-of<Mode> $mode Top-level monitor category. Always `web` today; the concrete behavior is described by `target` and `change_detection`.
+     * @param Schedule|ScheduleShape $schedule Run the monitor on a fixed interval defined by a frequency and a unit, e.g. every 6 hours or every 2 days. The total interval (frequency × unit) must be between 10 minutes and 1 year.
      * @param list<string> $tags User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed.
      * @param Webhook|WebhookShape|null $webhook
      * @param RequestOpts|null $requestOptions
@@ -80,22 +80,22 @@ public function __construct(private Client $client)
      * @throws APIException
      */
     public function create(
-        MonitorsExactChangeDetection|array|MonitorsSemanticChangeDetection $changeDetection,
         string $name,
-        Schedule|array $schedule,
         MonitorsPageTarget|array|MonitorsSitemapTarget|MonitorsExtractTarget $target,
+        MonitorsExactChangeDetection|array|MonitorsSemanticChangeDetection|null $changeDetection = null,
         Mode|string|null $mode = null,
+        Schedule|array|null $schedule = null,
         ?array $tags = null,
         Webhook|array|null $webhook = null,
         RequestOptions|array|null $requestOptions = null,
     ): MonitorNewResponse {
         $params = Util::removeNulls(
             [
-                'changeDetection' => $changeDetection,
                 'name' => $name,
-                'schedule' => $schedule,
                 'target' => $target,
+                'changeDetection' => $changeDetection,
                 'mode' => $mode,
+                'schedule' => $schedule,
                 'tags' => $tags,
                 'webhook' => $webhook,
             ],
diff --git a/tests/Services/MonitorsTest.php b/tests/Services/MonitorsTest.php
index d60e90d..f9bef0f 100644
--- a/tests/Services/MonitorsTest.php
+++ b/tests/Services/MonitorsTest.php
@@ -48,9 +48,7 @@ public function testCreate(): void
         }
 
         $result = $this->client->monitors->create(
-            changeDetection: ['type' => 'exact'],
             name: 'Acme pricing page',
-            schedule: ['frequency' => 6, 'type' => 'interval', 'unit' => 'hours'],
             target: ['type' => 'page', 'url' => 'https://acme.com/pricing'],
         );
 
@@ -66,15 +64,15 @@ public function testCreateWithOptionalParams(): void
         }
 
         $result = $this->client->monitors->create(
-            changeDetection: ['type' => 'exact'],
             name: 'Acme pricing page',
-            schedule: ['frequency' => 6, 'type' => 'interval', 'unit' => 'hours'],
             target: [
                 'type' => 'page',
                 'url' => 'https://acme.com/pricing',
                 'normalizeWhitespace' => true,
             ],
+            changeDetection: ['type' => 'exact'],
             mode: 'web',
+            schedule: ['frequency' => 6, 'type' => 'interval', 'unit' => 'hours'],
             tags: ['pricing', 'competitor'],
             webhook: [
                 'url' => 'https://example.com/webhook',

From ead89a68d802e28bce49e8fbbecd9afbd064abfc Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Mon, 27 Jul 2026 06:43:20 +0000
Subject: [PATCH 2/3] feat(api): api update

---
 .stats.yml                                    |  4 +--
 .../MonitorsSemanticChangeDetection.php       |  2 +-
 .../Target/MonitorsPageTarget.php             | 26 +++++++++++++++++--
 .../MonitorsSemanticChangeDetection.php       |  2 +-
 .../Target/MonitorsPageTarget.php             | 26 +++++++++++++++++--
 .../MonitorsSemanticChangeDetection.php       |  2 +-
 .../Data/Target/MonitorsPageTarget.php        | 26 +++++++++++++++++--
 .../MonitorsSemanticChangeDetection.php       |  2 +-
 .../Target/MonitorsPageTarget.php             | 26 +++++++++++++++++--
 .../MonitorsSemanticChangeDetection.php       |  2 +-
 .../Target/MonitorsPageTarget.php             | 26 +++++++++++++++++--
 .../MonitorsSemanticChangeDetection.php       |  2 +-
 .../Target/MonitorsPageTarget.php             | 26 +++++++++++++++++--
 tests/Services/MonitorsTest.php               |  1 +
 14 files changed, 153 insertions(+), 20 deletions(-)

diff --git a/.stats.yml b/.stats.yml
index 6da4682..3f4cd2e 100644
--- a/.stats.yml
+++ b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 32
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-2bf2b44f6593c44b2948683469bbb2b09cd8e90c97b12057fac6220cf0d2eee7.yml
-openapi_spec_hash: ae8b5109ec997cac8d3e6ec96040f6c8
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-91f4286859fc23813c5255b877395c87dd81520c3913fdfdae3cfa343e1a4873.yml
+openapi_spec_hash: 71746b5b65f20617ee021e071d5f7f92
 config_hash: 70e7e80b5e87f94981bee396c6cd41e8
diff --git a/src/Monitors/MonitorCreateParams/ChangeDetection/MonitorsSemanticChangeDetection.php b/src/Monitors/MonitorCreateParams/ChangeDetection/MonitorsSemanticChangeDetection.php
index 2f32c23..a986e3e 100644
--- a/src/Monitors/MonitorCreateParams/ChangeDetection/MonitorsSemanticChangeDetection.php
+++ b/src/Monitors/MonitorCreateParams/ChangeDetection/MonitorsSemanticChangeDetection.php
@@ -10,7 +10,7 @@
 use ContextDev\Core\Contracts\BaseModel;
 
 /**
- * Detect meaning-level changes to tracked page content, ignoring cosmetic or paraphrase-only differences. Which changes are meaningful is judged against the extract target's `instructions` (and `schema`, when provided).
+ * Detect meaning-level changes to page content, ignoring cosmetic or instruction-irrelevant differences. Which changes are meaningful is judged against the page or extract target's `instructions` (and an extract target's `schema`, when provided).
  *
  * @phpstan-type MonitorsSemanticChangeDetectionShape = array{
  *   type: 'semantic', confidenceThreshold?: float|null
diff --git a/src/Monitors/MonitorCreateParams/Target/MonitorsPageTarget.php b/src/Monitors/MonitorCreateParams/Target/MonitorsPageTarget.php
index c5908ac..bc4b982 100644
--- a/src/Monitors/MonitorCreateParams/Target/MonitorsPageTarget.php
+++ b/src/Monitors/MonitorCreateParams/Target/MonitorsPageTarget.php
@@ -10,10 +10,13 @@
 use ContextDev\Core\Contracts\BaseModel;
 
 /**
- * Watch a single web page.
+ * Watch a single web page. Exact detection reports visible-text diffs; semantic detection judges confirmed stable diffs against `instructions`.
  *
  * @phpstan-type MonitorsPageTargetShape = array{
- *   type: 'page', url: string, normalizeWhitespace?: bool|null
+ *   type: 'page',
+ *   url: string,
+ *   instructions?: string|null,
+ *   normalizeWhitespace?: bool|null,
  * }
  */
 final class MonitorsPageTarget implements BaseModel
@@ -28,6 +31,12 @@ final class MonitorsPageTarget implements BaseModel
     #[Required]
     public string $url;
 
+    /**
+     * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred.
+     */
+    #[Optional]
+    public ?string $instructions;
+
     /**
      * Normalize whitespace before comparing or analyzing text.
      */
@@ -60,12 +69,14 @@ public function __construct()
      */
     public static function with(
         string $url,
+        ?string $instructions = null,
         ?bool $normalizeWhitespace = null
     ): self {
         $self = new self;
 
         $self['url'] = $url;
 
+        null !== $instructions && $self['instructions'] = $instructions;
         null !== $normalizeWhitespace && $self['normalizeWhitespace'] = $normalizeWhitespace;
 
         return $self;
@@ -90,6 +101,17 @@ public function withURL(string $url): self
         return $self;
     }
 
+    /**
+     * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred.
+     */
+    public function withInstructions(string $instructions): self
+    {
+        $self = clone $this;
+        $self['instructions'] = $instructions;
+
+        return $self;
+    }
+
     /**
      * Normalize whitespace before comparing or analyzing text.
      */
diff --git a/src/Monitors/MonitorGetResponse/ChangeDetection/MonitorsSemanticChangeDetection.php b/src/Monitors/MonitorGetResponse/ChangeDetection/MonitorsSemanticChangeDetection.php
index 1fe50cb..45361f5 100644
--- a/src/Monitors/MonitorGetResponse/ChangeDetection/MonitorsSemanticChangeDetection.php
+++ b/src/Monitors/MonitorGetResponse/ChangeDetection/MonitorsSemanticChangeDetection.php
@@ -10,7 +10,7 @@
 use ContextDev\Core\Contracts\BaseModel;
 
 /**
- * Detect meaning-level changes to tracked page content, ignoring cosmetic or paraphrase-only differences. Which changes are meaningful is judged against the extract target's `instructions` (and `schema`, when provided).
+ * Detect meaning-level changes to page content, ignoring cosmetic or instruction-irrelevant differences. Which changes are meaningful is judged against the page or extract target's `instructions` (and an extract target's `schema`, when provided).
  *
  * @phpstan-type MonitorsSemanticChangeDetectionShape = array{
  *   type: 'semantic', confidenceThreshold?: float|null
diff --git a/src/Monitors/MonitorGetResponse/Target/MonitorsPageTarget.php b/src/Monitors/MonitorGetResponse/Target/MonitorsPageTarget.php
index 0689dc3..5252039 100644
--- a/src/Monitors/MonitorGetResponse/Target/MonitorsPageTarget.php
+++ b/src/Monitors/MonitorGetResponse/Target/MonitorsPageTarget.php
@@ -10,10 +10,13 @@
 use ContextDev\Core\Contracts\BaseModel;
 
 /**
- * Watch a single web page.
+ * Watch a single web page. Exact detection reports visible-text diffs; semantic detection judges confirmed stable diffs against `instructions`.
  *
  * @phpstan-type MonitorsPageTargetShape = array{
- *   type: 'page', url: string, normalizeWhitespace?: bool|null
+ *   type: 'page',
+ *   url: string,
+ *   instructions?: string|null,
+ *   normalizeWhitespace?: bool|null,
  * }
  */
 final class MonitorsPageTarget implements BaseModel
@@ -28,6 +31,12 @@ final class MonitorsPageTarget implements BaseModel
     #[Required]
     public string $url;
 
+    /**
+     * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred.
+     */
+    #[Optional]
+    public ?string $instructions;
+
     /**
      * Normalize whitespace before comparing or analyzing text.
      */
@@ -60,12 +69,14 @@ public function __construct()
      */
     public static function with(
         string $url,
+        ?string $instructions = null,
         ?bool $normalizeWhitespace = null
     ): self {
         $self = new self;
 
         $self['url'] = $url;
 
+        null !== $instructions && $self['instructions'] = $instructions;
         null !== $normalizeWhitespace && $self['normalizeWhitespace'] = $normalizeWhitespace;
 
         return $self;
@@ -90,6 +101,17 @@ public function withURL(string $url): self
         return $self;
     }
 
+    /**
+     * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred.
+     */
+    public function withInstructions(string $instructions): self
+    {
+        $self = clone $this;
+        $self['instructions'] = $instructions;
+
+        return $self;
+    }
+
     /**
      * Normalize whitespace before comparing or analyzing text.
      */
diff --git a/src/Monitors/MonitorListResponse/Data/ChangeDetection/MonitorsSemanticChangeDetection.php b/src/Monitors/MonitorListResponse/Data/ChangeDetection/MonitorsSemanticChangeDetection.php
index bf1868d..711853a 100644
--- a/src/Monitors/MonitorListResponse/Data/ChangeDetection/MonitorsSemanticChangeDetection.php
+++ b/src/Monitors/MonitorListResponse/Data/ChangeDetection/MonitorsSemanticChangeDetection.php
@@ -10,7 +10,7 @@
 use ContextDev\Core\Contracts\BaseModel;
 
 /**
- * Detect meaning-level changes to tracked page content, ignoring cosmetic or paraphrase-only differences. Which changes are meaningful is judged against the extract target's `instructions` (and `schema`, when provided).
+ * Detect meaning-level changes to page content, ignoring cosmetic or instruction-irrelevant differences. Which changes are meaningful is judged against the page or extract target's `instructions` (and an extract target's `schema`, when provided).
  *
  * @phpstan-type MonitorsSemanticChangeDetectionShape = array{
  *   type: 'semantic', confidenceThreshold?: float|null
diff --git a/src/Monitors/MonitorListResponse/Data/Target/MonitorsPageTarget.php b/src/Monitors/MonitorListResponse/Data/Target/MonitorsPageTarget.php
index bff0489..b059142 100644
--- a/src/Monitors/MonitorListResponse/Data/Target/MonitorsPageTarget.php
+++ b/src/Monitors/MonitorListResponse/Data/Target/MonitorsPageTarget.php
@@ -10,10 +10,13 @@
 use ContextDev\Core\Contracts\BaseModel;
 
 /**
- * Watch a single web page.
+ * Watch a single web page. Exact detection reports visible-text diffs; semantic detection judges confirmed stable diffs against `instructions`.
  *
  * @phpstan-type MonitorsPageTargetShape = array{
- *   type: 'page', url: string, normalizeWhitespace?: bool|null
+ *   type: 'page',
+ *   url: string,
+ *   instructions?: string|null,
+ *   normalizeWhitespace?: bool|null,
  * }
  */
 final class MonitorsPageTarget implements BaseModel
@@ -28,6 +31,12 @@ final class MonitorsPageTarget implements BaseModel
     #[Required]
     public string $url;
 
+    /**
+     * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred.
+     */
+    #[Optional]
+    public ?string $instructions;
+
     /**
      * Normalize whitespace before comparing or analyzing text.
      */
@@ -60,12 +69,14 @@ public function __construct()
      */
     public static function with(
         string $url,
+        ?string $instructions = null,
         ?bool $normalizeWhitespace = null
     ): self {
         $self = new self;
 
         $self['url'] = $url;
 
+        null !== $instructions && $self['instructions'] = $instructions;
         null !== $normalizeWhitespace && $self['normalizeWhitespace'] = $normalizeWhitespace;
 
         return $self;
@@ -90,6 +101,17 @@ public function withURL(string $url): self
         return $self;
     }
 
+    /**
+     * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred.
+     */
+    public function withInstructions(string $instructions): self
+    {
+        $self = clone $this;
+        $self['instructions'] = $instructions;
+
+        return $self;
+    }
+
     /**
      * Normalize whitespace before comparing or analyzing text.
      */
diff --git a/src/Monitors/MonitorNewResponse/ChangeDetection/MonitorsSemanticChangeDetection.php b/src/Monitors/MonitorNewResponse/ChangeDetection/MonitorsSemanticChangeDetection.php
index 9ca859f..010fea7 100644
--- a/src/Monitors/MonitorNewResponse/ChangeDetection/MonitorsSemanticChangeDetection.php
+++ b/src/Monitors/MonitorNewResponse/ChangeDetection/MonitorsSemanticChangeDetection.php
@@ -10,7 +10,7 @@
 use ContextDev\Core\Contracts\BaseModel;
 
 /**
- * Detect meaning-level changes to tracked page content, ignoring cosmetic or paraphrase-only differences. Which changes are meaningful is judged against the extract target's `instructions` (and `schema`, when provided).
+ * Detect meaning-level changes to page content, ignoring cosmetic or instruction-irrelevant differences. Which changes are meaningful is judged against the page or extract target's `instructions` (and an extract target's `schema`, when provided).
  *
  * @phpstan-type MonitorsSemanticChangeDetectionShape = array{
  *   type: 'semantic', confidenceThreshold?: float|null
diff --git a/src/Monitors/MonitorNewResponse/Target/MonitorsPageTarget.php b/src/Monitors/MonitorNewResponse/Target/MonitorsPageTarget.php
index cb684a9..56c8a61 100644
--- a/src/Monitors/MonitorNewResponse/Target/MonitorsPageTarget.php
+++ b/src/Monitors/MonitorNewResponse/Target/MonitorsPageTarget.php
@@ -10,10 +10,13 @@
 use ContextDev\Core\Contracts\BaseModel;
 
 /**
- * Watch a single web page.
+ * Watch a single web page. Exact detection reports visible-text diffs; semantic detection judges confirmed stable diffs against `instructions`.
  *
  * @phpstan-type MonitorsPageTargetShape = array{
- *   type: 'page', url: string, normalizeWhitespace?: bool|null
+ *   type: 'page',
+ *   url: string,
+ *   instructions?: string|null,
+ *   normalizeWhitespace?: bool|null,
  * }
  */
 final class MonitorsPageTarget implements BaseModel
@@ -28,6 +31,12 @@ final class MonitorsPageTarget implements BaseModel
     #[Required]
     public string $url;
 
+    /**
+     * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred.
+     */
+    #[Optional]
+    public ?string $instructions;
+
     /**
      * Normalize whitespace before comparing or analyzing text.
      */
@@ -60,12 +69,14 @@ public function __construct()
      */
     public static function with(
         string $url,
+        ?string $instructions = null,
         ?bool $normalizeWhitespace = null
     ): self {
         $self = new self;
 
         $self['url'] = $url;
 
+        null !== $instructions && $self['instructions'] = $instructions;
         null !== $normalizeWhitespace && $self['normalizeWhitespace'] = $normalizeWhitespace;
 
         return $self;
@@ -90,6 +101,17 @@ public function withURL(string $url): self
         return $self;
     }
 
+    /**
+     * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred.
+     */
+    public function withInstructions(string $instructions): self
+    {
+        $self = clone $this;
+        $self['instructions'] = $instructions;
+
+        return $self;
+    }
+
     /**
      * Normalize whitespace before comparing or analyzing text.
      */
diff --git a/src/Monitors/MonitorUpdateParams/ChangeDetection/MonitorsSemanticChangeDetection.php b/src/Monitors/MonitorUpdateParams/ChangeDetection/MonitorsSemanticChangeDetection.php
index b25c452..8b75978 100644
--- a/src/Monitors/MonitorUpdateParams/ChangeDetection/MonitorsSemanticChangeDetection.php
+++ b/src/Monitors/MonitorUpdateParams/ChangeDetection/MonitorsSemanticChangeDetection.php
@@ -10,7 +10,7 @@
 use ContextDev\Core\Contracts\BaseModel;
 
 /**
- * Detect meaning-level changes to tracked page content, ignoring cosmetic or paraphrase-only differences. Which changes are meaningful is judged against the extract target's `instructions` (and `schema`, when provided).
+ * Detect meaning-level changes to page content, ignoring cosmetic or instruction-irrelevant differences. Which changes are meaningful is judged against the page or extract target's `instructions` (and an extract target's `schema`, when provided).
  *
  * @phpstan-type MonitorsSemanticChangeDetectionShape = array{
  *   type: 'semantic', confidenceThreshold?: float|null
diff --git a/src/Monitors/MonitorUpdateParams/Target/MonitorsPageTarget.php b/src/Monitors/MonitorUpdateParams/Target/MonitorsPageTarget.php
index 6e4bf1e..a86aa19 100644
--- a/src/Monitors/MonitorUpdateParams/Target/MonitorsPageTarget.php
+++ b/src/Monitors/MonitorUpdateParams/Target/MonitorsPageTarget.php
@@ -10,10 +10,13 @@
 use ContextDev\Core\Contracts\BaseModel;
 
 /**
- * Watch a single web page.
+ * Watch a single web page. Exact detection reports visible-text diffs; semantic detection judges confirmed stable diffs against `instructions`.
  *
  * @phpstan-type MonitorsPageTargetShape = array{
- *   type: 'page', url: string, normalizeWhitespace?: bool|null
+ *   type: 'page',
+ *   url: string,
+ *   instructions?: string|null,
+ *   normalizeWhitespace?: bool|null,
  * }
  */
 final class MonitorsPageTarget implements BaseModel
@@ -28,6 +31,12 @@ final class MonitorsPageTarget implements BaseModel
     #[Required]
     public string $url;
 
+    /**
+     * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred.
+     */
+    #[Optional]
+    public ?string $instructions;
+
     /**
      * Normalize whitespace before comparing or analyzing text.
      */
@@ -60,12 +69,14 @@ public function __construct()
      */
     public static function with(
         string $url,
+        ?string $instructions = null,
         ?bool $normalizeWhitespace = null
     ): self {
         $self = new self;
 
         $self['url'] = $url;
 
+        null !== $instructions && $self['instructions'] = $instructions;
         null !== $normalizeWhitespace && $self['normalizeWhitespace'] = $normalizeWhitespace;
 
         return $self;
@@ -90,6 +101,17 @@ public function withURL(string $url): self
         return $self;
     }
 
+    /**
+     * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred.
+     */
+    public function withInstructions(string $instructions): self
+    {
+        $self = clone $this;
+        $self['instructions'] = $instructions;
+
+        return $self;
+    }
+
     /**
      * Normalize whitespace before comparing or analyzing text.
      */
diff --git a/src/Monitors/MonitorUpdateResponse/ChangeDetection/MonitorsSemanticChangeDetection.php b/src/Monitors/MonitorUpdateResponse/ChangeDetection/MonitorsSemanticChangeDetection.php
index c1ccfc6..9c22a5e 100644
--- a/src/Monitors/MonitorUpdateResponse/ChangeDetection/MonitorsSemanticChangeDetection.php
+++ b/src/Monitors/MonitorUpdateResponse/ChangeDetection/MonitorsSemanticChangeDetection.php
@@ -10,7 +10,7 @@
 use ContextDev\Core\Contracts\BaseModel;
 
 /**
- * Detect meaning-level changes to tracked page content, ignoring cosmetic or paraphrase-only differences. Which changes are meaningful is judged against the extract target's `instructions` (and `schema`, when provided).
+ * Detect meaning-level changes to page content, ignoring cosmetic or instruction-irrelevant differences. Which changes are meaningful is judged against the page or extract target's `instructions` (and an extract target's `schema`, when provided).
  *
  * @phpstan-type MonitorsSemanticChangeDetectionShape = array{
  *   type: 'semantic', confidenceThreshold?: float|null
diff --git a/src/Monitors/MonitorUpdateResponse/Target/MonitorsPageTarget.php b/src/Monitors/MonitorUpdateResponse/Target/MonitorsPageTarget.php
index 80d0b6b..3fd1467 100644
--- a/src/Monitors/MonitorUpdateResponse/Target/MonitorsPageTarget.php
+++ b/src/Monitors/MonitorUpdateResponse/Target/MonitorsPageTarget.php
@@ -10,10 +10,13 @@
 use ContextDev\Core\Contracts\BaseModel;
 
 /**
- * Watch a single web page.
+ * Watch a single web page. Exact detection reports visible-text diffs; semantic detection judges confirmed stable diffs against `instructions`.
  *
  * @phpstan-type MonitorsPageTargetShape = array{
- *   type: 'page', url: string, normalizeWhitespace?: bool|null
+ *   type: 'page',
+ *   url: string,
+ *   instructions?: string|null,
+ *   normalizeWhitespace?: bool|null,
  * }
  */
 final class MonitorsPageTarget implements BaseModel
@@ -28,6 +31,12 @@ final class MonitorsPageTarget implements BaseModel
     #[Required]
     public string $url;
 
+    /**
+     * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred.
+     */
+    #[Optional]
+    public ?string $instructions;
+
     /**
      * Normalize whitespace before comparing or analyzing text.
      */
@@ -60,12 +69,14 @@ public function __construct()
      */
     public static function with(
         string $url,
+        ?string $instructions = null,
         ?bool $normalizeWhitespace = null
     ): self {
         $self = new self;
 
         $self['url'] = $url;
 
+        null !== $instructions && $self['instructions'] = $instructions;
         null !== $normalizeWhitespace && $self['normalizeWhitespace'] = $normalizeWhitespace;
 
         return $self;
@@ -90,6 +101,17 @@ public function withURL(string $url): self
         return $self;
     }
 
+    /**
+     * Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred.
+     */
+    public function withInstructions(string $instructions): self
+    {
+        $self = clone $this;
+        $self['instructions'] = $instructions;
+
+        return $self;
+    }
+
     /**
      * Normalize whitespace before comparing or analyzing text.
      */
diff --git a/tests/Services/MonitorsTest.php b/tests/Services/MonitorsTest.php
index f9bef0f..957feec 100644
--- a/tests/Services/MonitorsTest.php
+++ b/tests/Services/MonitorsTest.php
@@ -68,6 +68,7 @@ public function testCreateWithOptionalParams(): void
             target: [
                 'type' => 'page',
                 'url' => 'https://acme.com/pricing',
+                'instructions' => 'Report pricing or plan availability changes. Ignore counters, timestamps, testimonials, and navigation.',
                 'normalizeWhitespace' => true,
             ],
             changeDetection: ['type' => 'exact'],

From 24ab868706fd869af1d5b869c2abb5b5730e5e45 Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Mon, 27 Jul 2026 06:43:42 +0000
Subject: [PATCH 3/3] release: 2.6.0

---
 .release-please-manifest.json | 2 +-
 CHANGELOG.md                  | 9 +++++++++
 README.md                     | 2 +-
 src/Version.php               | 2 +-
 4 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/.release-please-manifest.json b/.release-please-manifest.json
index 4dedeae..511dd51 100644
--- a/.release-please-manifest.json
+++ b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "2.5.0"
+  ".": "2.6.0"
 }
\ No newline at end of file
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3a07e8d..1a958af 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,14 @@
 # Changelog
 
+## 2.6.0 (2026-07-27)
+
+Full Changelog: [v2.5.0...v2.6.0](https://github.com/context-dot-dev/context-php-sdk/compare/v2.5.0...v2.6.0)
+
+### Features
+
+* **api:** api update ([ead89a6](https://github.com/context-dot-dev/context-php-sdk/commit/ead89a68d802e28bce49e8fbbecd9afbd064abfc))
+* **api:** api update ([61f098d](https://github.com/context-dot-dev/context-php-sdk/commit/61f098d3e54db1a7ed6e927cfd0a4b036ceb97c9))
+
 ## 2.5.0 (2026-07-22)
 
 Full Changelog: [v2.4.0...v2.5.0](https://github.com/context-dot-dev/context-php-sdk/compare/v2.4.0...v2.5.0)
diff --git a/README.md b/README.md
index ca69c9f..2f5e06f 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ The REST API documentation can be found on [docs.context.dev](https://docs.conte
 <!-- x-release-please-start-version -->
 
 ```
-composer require "context-dev/context-dev-php 2.5.0"
+composer require "context-dev/context-dev-php 2.6.0"
 ```
 
 <!-- x-release-please-end -->
diff --git a/src/Version.php b/src/Version.php
index 1c11a97..f690bfb 100644
--- a/src/Version.php
+++ b/src/Version.php
@@ -5,5 +5,5 @@
 namespace ContextDev;
 
 // x-release-please-start-version
-const VERSION = '2.5.0';
+const VERSION = '2.6.0';
 // x-release-please-end