release: 0.21.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.20.0"
+  ".": "0.21.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 27
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/moderation-api/moderation-api-cbf656f40e43acf60d9596f78204f031dc8c7205626df8f05ce8e88bcf49b597.yml
-openapi_spec_hash: 23be5a56248a1a575b34833eb7e7fe49
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/moderation-api/moderation-api-9c5291067ec36cba0c9ef772c5c8eb10238fb332f1f25d0e31f3f2ad87c24e5e.yml
+openapi_spec_hash: 790cc0a36d6ed693c06a285c441ab977
 config_hash: 9d144cc6c49d3fd53e5b4472c1e22165

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.21.0 (2026-06-02)
+
+Full Changelog: [v0.20.0...v0.21.0](https://github.com/moderation-api/sdk-php/compare/v0.20.0...v0.21.0)
+
+### Features
+
+* **api:** api update ([b376b1d](https://github.com/moderation-api/sdk-php/commit/b376b1d8336566576a93cd16c54186ef22f62bb5))
+
 ## 0.20.0 (2026-06-02)
 
 Full Changelog: [v0.19.0...v0.20.0](https://github.com/moderation-api/sdk-php/compare/v0.19.0...v0.20.0)

README.md

@@ -11,7 +11,7 @@ The REST API documentation can be found on [docs.moderationapi.com](https://docs
 <!-- x-release-please-start-version -->
 
 ```
-composer require "moderation-api/sdk-php 0.20.0"
+composer require "moderation-api/sdk-php 0.21.0"
 ```
 
 <!-- x-release-please-end -->

src/Content/ContentSubmitParams.php

@@ -4,6 +4,7 @@
 
 namespace ModerationAPI\Content;
 
+use ModerationAPI\Content\ContentSubmitParams\ClientAction;
 use ModerationAPI\Content\ContentSubmitParams\Content\Audio;
 use ModerationAPI\Content\ContentSubmitParams\Content\Image;
 use ModerationAPI\Content\ContentSubmitParams\Content\Object_;
@@ -23,12 +24,14 @@
  * @phpstan-import-type ContentVariants from \ModerationAPI\Content\ContentSubmitParams\Content
  * @phpstan-import-type PolicyVariants from \ModerationAPI\Content\ContentSubmitParams\Policy
  * @phpstan-import-type ContentShape from \ModerationAPI\Content\ContentSubmitParams\Content
+ * @phpstan-import-type ClientActionShape from \ModerationAPI\Content\ContentSubmitParams\ClientAction
  * @phpstan-import-type PolicyShape from \ModerationAPI\Content\ContentSubmitParams\Policy
  *
  * @phpstan-type ContentSubmitParamsShape = array{
  *   content: ContentShape,
  *   authorID?: string|null,
  *   channel?: string|null,
+ *   clientAction?: null|ClientAction|ClientActionShape,
  *   contentID?: string|null,
  *   conversationID?: string|null,
  *   doNotStore?: bool|null,
@@ -64,6 +67,12 @@ final class ContentSubmitParams implements BaseModel
     #[Optional]
     public ?string $channel;
 
+    /**
+     * A recommendation from your own client-side flagging (e.g. a banned-IP list or a third-party tool). Feeds the rules engine and can escalate or override the recommended action. Does not change whether our analysis flagged the content.
+     */
+    #[Optional]
+    public ?ClientAction $clientAction;
+
     /**
      * The unique ID of the content in your database.
      */
@@ -137,6 +146,7 @@ public function __construct()
      * You must use named parameters to construct any parameters with a default value.
      *
      * @param ContentShape $content
+     * @param ClientAction|ClientActionShape|null $clientAction
      * @param array<string,mixed>|null $metadata
      * @param MetaType|value-of<MetaType>|null $metaType
      * @param list<PolicyShape>|null $policies
@@ -145,6 +155,7 @@ public static function with(
         Text|array|Image|Video|Audio|Object_ $content,
         ?string $authorID = null,
         ?string $channel = null,
+        ClientAction|array|null $clientAction = null,
         ?string $contentID = null,
         ?string $conversationID = null,
         ?bool $doNotStore = null,
@@ -159,6 +170,7 @@ public static function with(
 
         null !== $authorID && $self['authorID'] = $authorID;
         null !== $channel && $self['channel'] = $channel;
+        null !== $clientAction && $self['clientAction'] = $clientAction;
         null !== $contentID && $self['contentID'] = $contentID;
         null !== $conversationID && $self['conversationID'] = $conversationID;
         null !== $doNotStore && $self['doNotStore'] = $doNotStore;
@@ -206,6 +218,19 @@ public function withChannel(string $channel): self
         return $self;
     }
 
+    /**
+     * A recommendation from your own client-side flagging (e.g. a banned-IP list or a third-party tool). Feeds the rules engine and can escalate or override the recommended action. Does not change whether our analysis flagged the content.
+     *
+     * @param ClientAction|ClientActionShape $clientAction
+     */
+    public function withClientAction(ClientAction|array $clientAction): self
+    {
+        $self = clone $this;
+        $self['clientAction'] = $clientAction;
+
+        return $self;
+    }
+
     /**
      * The unique ID of the content in your database.
      */

src/Content/ContentSubmitParams/ClientAction.php

@@ -0,0 +1,148 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ModerationAPI\Content\ContentSubmitParams;
+
+use ModerationAPI\Content\ContentSubmitParams\ClientAction\Action;
+use ModerationAPI\Content\ContentSubmitParams\ClientAction\Behavior;
+use ModerationAPI\Core\Attributes\Optional;
+use ModerationAPI\Core\Attributes\Required;
+use ModerationAPI\Core\Concerns\SdkModel;
+use ModerationAPI\Core\Contracts\BaseModel;
+
+/**
+ * A recommendation from your own client-side flagging (e.g. a banned-IP list or a third-party tool). Feeds the rules engine and can escalate or override the recommended action. Does not change whether our analysis flagged the content.
+ *
+ * @phpstan-type ClientActionShape = array{
+ *   action: Action|value-of<Action>,
+ *   behavior?: null|Behavior|value-of<Behavior>,
+ *   reason?: string|null,
+ *   source?: string|null,
+ * }
+ */
+final class ClientAction implements BaseModel
+{
+    /** @use SdkModel<ClientActionShape> */
+    use SdkModel;
+
+    /**
+     * Your recommendation for the content: allow, review, or reject.
+     *
+     * @var value-of<Action> $action
+     */
+    #[Required(enum: Action::class)]
+    public string $action;
+
+    /**
+     * How your recommendation combines with ours. Defaults to 'escalate', which only applies it when stricter than ours; 'override' replaces ours outright.
+     *
+     * @var value-of<Behavior>|null $behavior
+     */
+    #[Optional(enum: Behavior::class)]
+    public ?string $behavior;
+
+    /**
+     * A human-readable explanation for your recommendation.
+     */
+    #[Optional]
+    public ?string $reason;
+
+    /**
+     * Where your recommendation came from, e.g. "banned-ip".
+     */
+    #[Optional]
+    public ?string $source;
+
+    /**
+     * `new ClientAction()` is missing required properties by the API.
+     *
+     * To enforce required parameters use
+     * ```
+     * ClientAction::with(action: ...)
+     * ```
+     *
+     * Otherwise ensure the following setters are called
+     *
+     * ```
+     * (new ClientAction)->withAction(...)
+     * ```
+     */
+    public function __construct()
+    {
+        $this->initialize();
+    }
+
+    /**
+     * Construct an instance from the required parameters.
+     *
+     * You must use named parameters to construct any parameters with a default value.
+     *
+     * @param Action|value-of<Action> $action
+     * @param Behavior|value-of<Behavior>|null $behavior
+     */
+    public static function with(
+        Action|string $action,
+        Behavior|string|null $behavior = null,
+        ?string $reason = null,
+        ?string $source = null,
+    ): self {
+        $self = new self;
+
+        $self['action'] = $action;
+
+        null !== $behavior && $self['behavior'] = $behavior;
+        null !== $reason && $self['reason'] = $reason;
+        null !== $source && $self['source'] = $source;
+
+        return $self;
+    }
+
+    /**
+     * Your recommendation for the content: allow, review, or reject.
+     *
+     * @param Action|value-of<Action> $action
+     */
+    public function withAction(Action|string $action): self
+    {
+        $self = clone $this;
+        $self['action'] = $action;
+
+        return $self;
+    }
+
+    /**
+     * How your recommendation combines with ours. Defaults to 'escalate', which only applies it when stricter than ours; 'override' replaces ours outright.
+     *
+     * @param Behavior|value-of<Behavior> $behavior
+     */
+    public function withBehavior(Behavior|string $behavior): self
+    {
+        $self = clone $this;
+        $self['behavior'] = $behavior;
+
+        return $self;
+    }
+
+    /**
+     * A human-readable explanation for your recommendation.
+     */
+    public function withReason(string $reason): self
+    {
+        $self = clone $this;
+        $self['reason'] = $reason;
+
+        return $self;
+    }
+
+    /**
+     * Where your recommendation came from, e.g. "banned-ip".
+     */
+    public function withSource(string $source): self
+    {
+        $self = clone $this;
+        $self['source'] = $source;
+
+        return $self;
+    }
+}

src/Content/ContentSubmitParams/ClientAction/Action.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ModerationAPI\Content\ContentSubmitParams\ClientAction;
+
+/**
+ * Your recommendation for the content: allow, review, or reject.
+ */
+enum Action: string
+{
+    case REVIEW = 'review';
+
+    case ALLOW = 'allow';
+
+    case REJECT = 'reject';
+}

src/Content/ContentSubmitParams/ClientAction/Behavior.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ModerationAPI\Content\ContentSubmitParams\ClientAction;
+
+/**
+ * How your recommendation combines with ours. Defaults to 'escalate', which only applies it when stricter than ours; 'override' replaces ours outright.
+ */
+enum Behavior: string
+{
+    case OVERRIDE = 'override';
+
+    case ESCALATE = 'escalate';
+}

src/Content/ContentSubmitResponse/Recommendation/ReasonCode.php

@@ -23,4 +23,6 @@ enum ReasonCode: string
     case RULE_DEFAULT = 'rule_default';
 
     case RULE_FALLBACK = 'rule_fallback';
+
+    case CLIENT_OVERRIDE = 'client_override';
 }