feat(audiences): POST /audiences persists given Apollo filters verbatim (QE-CHIRO-1102) (#482)

An audience whose filters the caller already holds (titles + location) could
only be persisted through the LLM refine loop, so it could never be switched
to the QuickEnrich serve source. The new route stores the filters as given
(they are the audience's identity on /search/next) and counts them with a
free dry-run.

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: KevinLourd

openapi.json

@@ -5506,6 +5506,103 @@
           "quickenrich"
         ]
       },
+      "CreateAudienceFromFiltersResponse": {
+        "type": "object",
+        "properties": {
+          "apolloAudienceId": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "name": {
+            "type": "string"
+          },
+          "filters": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/SearchFilters"
+              },
+              {
+                "description": "Apollo People API Search filters using Apollo-native field names. All filters are combined using AND. Start broad and narrow down to avoid empty results."
+              }
+            ]
+          },
+          "count": {
+            "type": "integer",
+            "description": "Live Apollo match-count for the filters, from a free dry-run."
+          },
+          "serveSource": {
+            "type": "string",
+            "enum": [
+              "apollo",
+              "quickenrich"
+            ]
+          },
+          "quickenrich": {
+            "type": "object",
+            "properties": {
+              "expressible": {
+                "type": "boolean"
+              },
+              "reasons": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            },
+            "required": [
+              "expressible",
+              "reasons"
+            ]
+          }
+        },
+        "required": [
+          "apolloAudienceId",
+          "name",
+          "filters",
+          "count",
+          "serveSource",
+          "quickenrich"
+        ]
+      },
+      "CreateAudienceFromFiltersRequest": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200,
+            "description": "Audience name (English).",
+            "example": "US Chiropractors (by title)"
+          },
+          "description": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2000,
+            "description": "What the audience is, in one or two sentences (English)."
+          },
+          "brandId": {
+            "type": "string",
+            "description": "Brand the audience belongs to."
+          },
+          "filters": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/SearchFilters"
+              },
+              {
+                "description": "Apollo-native People Search filters, stored VERBATIM. A consumer that forwards the same object to /search/next is served from this audience (it is the audience's identity on that route, e.g. for its QuickEnrich serve source). A buying signal goes through POST /audiences/signal."
+              }
+            ]
+          }
+        },
+        "required": [
+          "name",
+          "description",
+          "filters"
+        ],
+        "additionalProperties": false
+      },
       "ServeSourceResponse": {
         "type": "object",
         "properties": {
@@ -8513,6 +8610,96 @@
         }
       }
     },
+    "/audiences": {
+      "post": {
+        "summary": "Persist an Apollo audience from given Apollo-native filters",
+        "description": "Stores the filters exactly as given (no LLM, no rewrite), counted by a free Apollo dry-run. The returned apolloAudienceId can then be switched to the QuickEnrich serve source (PATCH /audiences/{apolloAudienceId}/serve-source) and bound to a consumer audience whose stored filters are the same object.",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "x-api-key",
+            "in": "header"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "x-org-id",
+            "in": "header"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "x-user-id",
+            "in": "header"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "x-brand-id",
+            "in": "header"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "x-run-id",
+            "in": "header"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateAudienceFromFiltersRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Persisted",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CreateAudienceFromFiltersResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/audiences/{apolloAudienceId}/serve-source": {
       "patch": {
         "summary": "Switch an audience between the Apollo and the QuickEnrich serve path",

src/routes/audiences.ts

@@ -34,7 +34,7 @@ import { toCreditAlertIdentity } from "../lib/credit-alert.js";
 import { SuggestFromSegmentRequestSchema, ApolloNativeSearchFiltersSchema, AudienceCompaniesQuerySchema } from "../schemas.js";
 import { providerErrorFields } from "../lib/provider-error.js";
 import { planQuickenrich } from "../lib/quickenrich.js";
-import { ServeSourceRequestSchema, SignalCoverageRequestSchema, CreateSignalAudienceRequestSchema, SearchFiltersSchema, APOLLO_BUYING_SIGNAL_TYPES } from "../schemas.js";
+import { ServeSourceRequestSchema, CreateAudienceFromFiltersRequestSchema, SignalCoverageRequestSchema, CreateSignalAudienceRequestSchema, SearchFiltersSchema, APOLLO_BUYING_SIGNAL_TYPES } from "../schemas.js";
 import { signalConflicts, signalWindow, utcDay, SignalNotApolloSearchableError, type BuyingSignalSpec, type BuyingSignalType } from "../lib/buying-signal-spec.js";
 import { filtersBesideEngagement } from "../lib/linkedin-engagement.js";
 import { parseCompetitorPage } from "../lib/linkedin-engagement-spec.js";
@@ -219,6 +219,50 @@ function serveSourceFields(serveSource: string, filters: Record<string, unknown>
   };
 }
 
+/**
+ * POST /audiences — persist an audience from Apollo-native filters the caller
+ * already holds (no refine loop, no LLM). The filters are stored VERBATIM:
+ * /search/next recognises a QuickEnrich audience by jsonb equality with the
+ * search params its consumer forwards, so any rewrite here would make the row
+ * unreachable. Counted by a free dry-run so it is born with its real size.
+ */
+router.post("/audiences", serviceAuth, async (req: AuthenticatedRequest, res) => {
+  try {
+    const parsed = CreateAudienceFromFiltersRequestSchema.safeParse(req.body);
+    if (!parsed.success) {
+      return res.status(400).json({ type: "validation", error: "Invalid request", details: parsed.error.flatten() });
+    }
+    const filters = req.body.filters as Record<string, unknown>;
+    const brandId = parsed.data.brandId ?? req.brandIds?.[0] ?? null;
+    const { key: apolloApiKey } = await decryptKey(
+      req.orgId!,
+      req.userId!,
+      "apollo",
+      { callerMethod: "POST", callerPath: "/audiences" },
+      { brandIds: brandId ? [brandId] : req.brandIds, featureSlug: req.featureSlug, workflowSlug: req.workflowSlug },
+    );
+    const count = await dryRunCount(apolloApiKey, filters, toCreditAlertIdentity(req));
+    const now = new Date();
+    const [row] = await db
+      .insert(apolloAudiences)
+      .values({
+        orgId: req.orgId!,
+        userId: req.userId ?? null,
+        brandId,
+        name: parsed.data.name,
+        description: parsed.data.description,
+        filters,
+        count,
+        countRefreshedAt: now,
+      })
+      .returning();
+    res.status(201).json({ apolloAudienceId: row.id, name: parsed.data.name, filters, count, ...serveSourceFields(row.serveSource ?? "apollo", filters) });
+  } catch (error) {
+    console.error("[Apollo Service][POST /audiences] ERROR:", error);
+    res.status(500).json({ type: "internal", error: error instanceof Error ? errorMessage(error) : "Internal server error", ...providerErrorFields(error) });
+  }
+});
+
 /**
  * PATCH /audiences/:apolloAudienceId/serve-source — switch where /search/next
  * sources this audience's people. `quickenrich` = free QuickEnrich search +

src/schemas.ts

@@ -2003,6 +2003,30 @@ const AudienceResponseSchema = z
   })
   .openapi("AudienceResponse");
 
+export const CreateAudienceFromFiltersRequestSchema = z
+  .object({
+    name: z.string().min(1).max(200).openapi({ description: "Audience name (English).", example: "US Chiropractors (by title)" }),
+    description: z.string().min(1).max(2000).openapi({ description: "What the audience is, in one or two sentences (English)." }),
+    brandId: z.string().optional().openapi({ description: "Brand the audience belongs to." }),
+    filters: ApolloNativeSearchFiltersSchema.refine((f) => Object.keys(f).length > 0, { message: "filters must state at least one constraint" }).openapi({
+      description:
+        "Apollo-native People Search filters, stored VERBATIM. A consumer that forwards the same object to /search/next is served from this audience (it is the audience's identity on that route, e.g. for its QuickEnrich serve source). A buying signal goes through POST /audiences/signal.",
+    }),
+  })
+  .strict()
+  .openapi("CreateAudienceFromFiltersRequest");
+
+const CreateAudienceFromFiltersResponseSchema = z
+  .object({
+    apolloAudienceId: z.string().uuid(),
+    name: z.string(),
+    filters: ApolloNativeSearchFiltersSchema,
+    count: z.number().int().openapi({ description: "Live Apollo match-count for the filters, from a free dry-run." }),
+    serveSource: z.enum(["apollo", "quickenrich"]),
+    quickenrich: z.object({ expressible: z.boolean(), reasons: z.array(z.string()) }),
+  })
+  .openapi("CreateAudienceFromFiltersResponse");
+
 export const ServeSourceRequestSchema = z
   .object({ serveSource: z.enum(["apollo", "quickenrich"]) })
   .openapi("ServeSourceRequest");
@@ -2062,6 +2086,23 @@ registry.registerPath({
   },
 });
 
+registry.registerPath({
+  method: "post",
+  path: "/audiences",
+  summary: "Persist an Apollo audience from given Apollo-native filters",
+  description:
+    "Stores the filters exactly as given (no LLM, no rewrite), counted by a free Apollo dry-run. The returned apolloAudienceId can then be switched to the QuickEnrich serve source (PATCH /audiences/{apolloAudienceId}/serve-source) and bound to a consumer audience whose stored filters are the same object.",
+  request: {
+    headers: audienceHeaders,
+    body: { content: { "application/json": { schema: CreateAudienceFromFiltersRequestSchema } }, required: true },
+  },
+  responses: {
+    201: { description: "Persisted", content: { "application/json": { schema: CreateAudienceFromFiltersResponseSchema } } },
+    400: { description: "Validation error", content: { "application/json": { schema: ErrorResponseSchema } } },
+    500: { description: "Internal server error", content: { "application/json": { schema: ErrorResponseSchema } } },
+  },
+});
+
 registry.registerPath({
   method: "patch",
   path: "/audiences/{apolloAudienceId}/serve-source",

tests/unit/audiences.test.ts

@@ -188,6 +188,38 @@ describe("Apollo audience endpoints", () => {
     app = await createApp();
   });
 
+  describe("POST /audiences (persist from given filters, QE-CHIRO-1102)", () => {
+    const TITLES = { person_titles: ["Chiropractor", "Doctor of Chiropractic", "Chiropractic Physician"], person_locations: ["United States"] };
+    // No LLM on this route: drop the outer queued model turns so they do not
+    // leak into the next test's queue.
+    beforeEach(() => {
+      mockChatComplete.mockReset();
+    });
+
+    it("stores the filters verbatim, counts them, no LLM, and says QuickEnrich can serve them", async () => {
+      setCounts(5657);
+      const res = await request(app)
+        .post("/audiences")
+        .set(HEADERS)
+        .send({ name: "US Chiropractors (by title)", description: "Chiropractors in the US", brandId: "brand-1", filters: TITLES })
+        .expect(201);
+      expect(res.body.apolloAudienceId).toBe("aud-1");
+      expect(res.body.count).toBe(5657);
+      expect(res.body.filters).toEqual(TITLES);
+      expect(res.body.serveSource).toBe("apollo");
+      expect(res.body.quickenrich).toEqual({ expressible: true, reasons: [] });
+      expect(state.insertedRows[0]).toMatchObject({ orgId: "org-1", brandId: "brand-1", filters: TITLES, count: 5657 });
+      expect(mockChatComplete).not.toHaveBeenCalled();
+    });
+
+    it("refuses empty filters, a non-native key and a buying signal", async () => {
+      for (const filters of [{}, { personTitles: ["x"] }, { person_titles: ["x"], buying_signal: { type: "hiring", window_days: 30 } }]) {
+        await request(app).post("/audiences").set(HEADERS).send({ name: "n", description: "d", filters }).expect(400);
+      }
+      expect(state.insertedRows).toEqual([]);
+    });
+  });
+
   it("POST /suggest-from-segment persists and returns {apolloAudienceId, filters, count}", async () => {
     setCounts(1000, 42000);