feat(ACI): Add API documentation for OrganizationDetectorIndexEndpoint POST by ceorourke · Pull Request #105882 · getsentry/sentry

ceorourke · 2026-01-08T00:50:29Z

Follow up to #106025 to add documentation for the POST OrganizationDetectorIndexEndpoint.

This will not be published yet, but in order to deploy this in pieces we'll set the publish_status to PUBLIC all at once and add the sidebar item for workflow engine.

The POST endpoint handles multiple detector types with various additional body params which isn't supported in our API documentation (it expects a single serializer), so I've done something similar to how we document the issue alert creation endpoint. This will need updating if we add more detector types, but unless the documentation framework is changed to support multiple serializers this is the best we can do.

localhost_3000_api_workflows_create-a-monitor-for-a-project_

src/sentry/snuba/snuba_query_validator.py

src/sentry/workflow_engine/endpoints/organization_detector_index.py

src/sentry/monitors/endpoints/organization_monitor_index.py

src/sentry/workflow_engine/endpoints/validators/base/detector.py

ceorourke · 2026-01-09T21:50:27Z

src/sentry/workflow_engine/endpoints/validators/base/detector.py


-    @property
-    def data_sources(self) -> serializers.ListField:
-        # TODO - improve typing here to enforce that the child is the correct type


The API docs do not currently support a single endpoint having multiple serializers as we have for detectors. In order to unblock deprecation I am sort of hacking this - every detector type except for the error detector has data_sources, and in order to get that to show up in the documentation I had to add it to the base detector and remove the not implemented definition here. I know this is not ideal, but it's the best we can do right now.

ceorourke · 2026-01-09T21:51:17Z

src/sentry/workflow_engine/endpoints/organization_detector_index.py

        parameters=[
            GlobalParams.ORG_ID_OR_SLUG,
        ],
-        request=PolymorphicProxySerializer(


This unfortunately doesn't work for the API docs even though it's a part of DRF spectacular. It generates a "one of many" that the API docs fail when trying to parse.

ceorourke · 2026-01-12T22:21:39Z

src/sentry/workflow_engine/endpoints/organization_detector_index.py


    @extend_schema(
-        operation_id="Create a Detector",
+        operation_id="Create a Monitor for a Project",


I can't make this titled "Create a Monitor" because there's already a published cron endpoint with that title. Since you need to supply a project ID here anyway I think it's ok.

mifu67

Looks good to me; @saponifi3d let me know if you want to take a look, otherwise I'll approve.

mifu67 · 2026-01-14T22:39:54Z

src/sentry/workflow_engine/endpoints/validators/base/detector.py

-    description = serializers.CharField(required=False, allow_null=True, allow_blank=True)
-    enabled = serializers.BooleanField(required=False)
-    condition_group = BaseDataConditionGroupValidator(required=False)
+    type = serializers.CharField(help_text="The type of monitor - 'metric_issue'")


Should we list potential monitor types here?

I removed the other types (crons and uptime) for the time being since we're not documenting how to make those at this time. I'm going to have the crons team add to this with their payloads.

mifu67 · 2026-01-14T22:44:01Z

src/sentry/workflow_engine/endpoints/validators/base/detector.py

+        required=False,
+        allow_null=True,
+        allow_blank=True,
+        help_text="A description of the monitor. Will be displayed in the resulting notification.",


Monitors don't send notifications by default, but up to you on changing this.

Do you think I should completely leave out the last sentence? It can be a nice surprise that it shows up if there is a notification 😓

🤔 maybe it will be used in the resulting issue? That's really where it's coming from on the notification, and where the description goes for the monitor.

saponifi3d · 2026-01-15T18:18:33Z

src/sentry/apidocs/examples/workflow_engine_examples.py

+    CREATE_DETECTOR = [
+        OpenApiExample(
+            "Monitor successfully created",
+            value={


🤔 not for today / this pr, but i wonder if we could generate these responses from the API so it automatically stays up to date.

src/sentry/workflow_engine/endpoints/validators/base/detector.py

saponifi3d · 2026-01-15T18:23:15Z

src/sentry/workflow_engine/endpoints/validators/base/detector.py

+        required=False,
+        allow_null=True,
+        allow_blank=True,
+        help_text="A description of the monitor. Will be displayed in the resulting notification.",


🤔 maybe it will be used in the resulting issue? That's really where it's coming from on the notification, and where the description goes for the monitor.

saponifi3d · 2026-01-15T18:25:05Z

src/sentry/workflow_engine/endpoints/validators/base/detector.py

+    enabled = serializers.BooleanField(
+        required=False, help_text="Set to False if you want to disable the monitor."
+    )
+    condition_group = BaseDataConditionGroupValidator(


i wonder if this is something we should define generically or not. something like talking about the logic type then it being conditions, then having a list of different condition values / models etc that we can associate here. Is it possible to nest model documentation like that with drfspectaular?

I don't think we can do nesting, but as an example I think https://docs.sentry.io/api/alerts/create-a-metric-alert-rule-for-an-organization/ is one of the more complicated documented endpoints we have and this uses a very long docstring. I like that this one lists out eventTypes values for example.

saponifi3d · 2026-01-15T18:55:26Z

src/sentry/workflow_engine/endpoints/validators/base/detector.py

+            **Threshold & Change**
+            ```json
+                "id": "1234567",
+                "organizationId": "1",


Just thinking about the API itself, should / do we need to return the org id on the condition group? wonder if we can remove it and save a few bytes.

I'm not sure what it's used for in the response but this did make me realize it's not needed in the post body so I removed it 👍

src/sentry/workflow_engine/endpoints/organization_detector_index.py

ceorourke · 2026-01-15T23:03:10Z

@saponifi3d ok check it out again, I re-organized things so it's roughly in order of what you'd set up in the UI and I added descriptions and available options. The screenshot looks wonky but I swear if you click to open it in a new page and click once more it's normal looking.

src/sentry/workflow_engine/endpoints/validators/base/detector.py

malwilley

Incredibly thorough! Looks good to me, I couldn't find any errors.

github-actions bot added the Scope: Backend Automatically applied to PRs that change backend components label Jan 8, 2026

ceorourke commented Jan 8, 2026

View reviewed changes

src/sentry/snuba/snuba_query_validator.py Outdated Show resolved Hide resolved

ceorourke commented Jan 8, 2026

View reviewed changes

src/sentry/workflow_engine/endpoints/organization_detector_index.py Outdated Show resolved Hide resolved

vercel bot deployed to Preview January 8, 2026 00:52 View deployment

vercel bot deployed to Preview January 8, 2026 22:26 View deployment

ceorourke changed the title ~~feat(ACI): Add API documentation~~ feat(ACI): Add API documentation for OrganizationDetectorIndexEndpoint GET and POST Jan 9, 2026

vercel bot deployed to Preview January 9, 2026 00:35 View deployment

vercel bot deployed to Preview January 9, 2026 18:10 View deployment

vercel bot deployed to Preview January 9, 2026 20:14 View deployment

ceorourke commented Jan 9, 2026

View reviewed changes

src/sentry/monitors/endpoints/organization_monitor_index.py Outdated Show resolved Hide resolved

vercel bot deployed to Preview January 9, 2026 21:49 View deployment

ceorourke changed the title ~~feat(ACI): Add API documentation for OrganizationDetectorIndexEndpoint GET and POST~~ feat(ACI): Add API documentation for OrganizationDetectorIndexEndpoint POST Jan 9, 2026

vercel bot deployed to Preview January 9, 2026 22:01 View deployment

vercel bot deployed to Preview January 9, 2026 22:35 View deployment

ceorourke force-pushed the ceorourke/publish-workflow-engine-endpoints branch from 06c3d40 to 06d1d5f Compare January 12, 2026 19:24

vercel bot deployed to Preview January 12, 2026 19:33 View deployment

vercel bot deployed to Preview January 12, 2026 20:26 View deployment

ceorourke commented Jan 12, 2026

View reviewed changes

ceorourke marked this pull request as ready for review January 12, 2026 20:27

ceorourke requested review from a team as code owners January 12, 2026 20:27

vercel bot deployed to Preview January 12, 2026 21:21 View deployment

ceorourke commented Jan 12, 2026

View reviewed changes

ceorourke mentioned this pull request Jan 13, 2026

feat(ACI): Document Organization Detector Details Endpoints #106148

Merged

mifu67 reviewed Jan 14, 2026

View reviewed changes

saponifi3d reviewed Jan 15, 2026

View reviewed changes

vercel bot deployed to Preview January 15, 2026 22:51 View deployment

ceorourke force-pushed the ceorourke/publish-workflow-engine-endpoints branch from 7701a6f to 9eba66a Compare January 15, 2026 22:57

vercel bot deployed to Preview January 15, 2026 23:00 View deployment

cathteng reviewed Jan 16, 2026

View reviewed changes

src/sentry/workflow_engine/endpoints/validators/base/detector.py Outdated Show resolved Hide resolved

ceorourke force-pushed the ceorourke/publish-workflow-engine-endpoints branch from 9eba66a to 807f979 Compare January 16, 2026 22:36

vercel bot deployed to Preview January 16, 2026 22:39 View deployment

ceorourke added 18 commits January 20, 2026 11:06

very rough start

0ed0100

got GET working

5204528

shadow publish

730230e

add example and base detector body params

bdd614d

use extend_schema_field to fix environment

1b0e795

get data sources in there

96eb6e6

clean up

4962221

dont need that

da67e72

Remove GET stuff

9b2ca72

change name

7fb332b

put that back

8c539f3

fix weird rebase mistakes

fb14674

put back example

920ee09

Add more data sources examples

e8c99bd

rm none

c93048a

linting

e3353fa

move help text into separate file

22249c8

linting

978aeae

ceorourke force-pushed the ceorourke/publish-workflow-engine-endpoints branch from 807f979 to 978aeae Compare January 20, 2026 19:11

vercel bot deployed to Preview January 20, 2026 19:15 View deployment

malwilley approved these changes Jan 20, 2026

View reviewed changes

oops put that stuff back

d7ea5f2

ceorourke force-pushed the ceorourke/publish-workflow-engine-endpoints branch from 1b64afb to d7ea5f2 Compare January 20, 2026 19:34

vercel bot deployed to Preview January 20, 2026 19:37 View deployment

ceorourke merged commit c842696 into master Jan 20, 2026
66 checks passed

ceorourke deleted the ceorourke/publish-workflow-engine-endpoints branch January 20, 2026 20:21

github-actions bot locked and limited conversation to collaborators Feb 5, 2026

Uh oh!

Conversation

ceorourke commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mifu67 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ceorourke commented Jan 15, 2026

Uh oh!

Uh oh!

malwilley left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ceorourke commented Jan 8, 2026 •

edited

Loading