> ## Documentation Index > Fetch the complete documentation index at: https://docs.getsales.io/llms.txt > Use this file to discover all available pages before exploring further. # Plan data source filters > Turn a description of who to find into a wire-ready filter set without creating anything: the step before create_data_source when the user should see or edit what will be searched. Paid: the AI parse costs one credit per call. It reads the words into facets (location, industry, current and past company, school, seniority, job function, company headcount, titles as free text) and the platform pool resolves every id-bearing term; a term with no id lands in result.unresolved, never faked. Facets are ANDed and the values inside one facet ORed; there are no exclusion filters, so describe who to find, never who to leave out. A facet keeps at most 10 values: the first ten stay, the dropped terms are named in result.warnings. Hand the answer to create_data_source as is: type and object_type from the result, name = suggested_name, payload = {filters, prompt: } (find_people adds payload.company_sids). create_data_source with payload.prompt alone plans the same way at its first collect step, so call this only when the plan must be seen first. Refusals: 422 on prompt when nothing usable was read (ai_parse_failed or ai_empty_filter: rephrase with roles, places or industries); a busy pool answers 503 service_unavailable (context.reason infrastructure_unavailable or search_in_flight) or 429 rate_limited (pool_rate_limited), each with context.retry_after: wait until then, or create the source with the prompt alone and let its collector plan at the pool's pace. Contract: - MCP tool `plan_data_source_filters`, registry package `mcp.playtables/data_sources`, mount `playtables.sources`. - Operation `action`, response envelope `action`. - Flags: none. ## OpenAPI ````yaml /api-reference/playtables/openapi.yaml post /api/data-sources/ai-plan openapi: 3.0.3 info: title: 'GetSales public contract: gs.service.playtables' description: >- The data platform and the outreach engine: tables of people and companies, their enrichment columns, cells and runs, the data sources that feed them, sender profiles, the stoplist, the activity feed, the credit ledger, and the multichannel workflows with their per-person journeys and tasks. GENERATED. This document is projected from the Zod MCP tool registry in `product/mcp/gs.mcp` (one tool per public endpoint, 1:1). Do not edit it by hand; edit the tool definition and regenerate with `pnpm openapi:public`. Surface: the public `/api` contract of `gs.service.playtables`, 142 operations. This is the only OpenAPI document the platform publishes. Internal (`/internal`) and health endpoints are deliberately absent: they are not part of any contract, they can change without notice, and the service source is their only description. Conventions: - Auth is a bearer JWT, optionally narrowed by the `Team-SID` header. - Every success body is an MCP envelope: `success: true` plus one typed `operation` shape (`search`, `get`, `create`, `update`, `delete`, `metrics`, `group_by`, `action`), and a `meta` block with `trace_id` for support. - Every failure is the same `McpError` envelope with a code from a fixed 16-code taxonomy, so a client maps errors once. - Lists page with `page_size` (0 to 500, default 50) plus an opaque forward `cursor`; `page_size: 0` returns counts only. - On `GET` and `DELETE`, object-valued query parameters (`filter`, `sort`) travel as JSON text and array-valued ones repeat as `name[]=value`. - The MCP-only `_meta` field (usage analytics) never reaches the backend and is not part of this contract. version: '1.0' contact: name: GetSales url: https://getsales.io email: support@getsales.io license: name: Proprietary url: https://getsales.io/terms servers: - url: https://beta.getsales.io/playtables/v1 description: >- Production (the gateway path on the beta ring; the origin is provisioned per DEPLOY_MAP.md) security: - BearerJwt: [] TeamSid: [] tags: - name: activities description: >- Registry package `mcp.playtables/activities`, served on MCP mount `playtables.journeys`. - name: activity_objects description: >- Registry package `mcp.playtables/activity_objects`, served on MCP mount `playtables.people`. - name: companies description: >- Registry package `mcp.playtables/companies`, served on MCP mount `playtables.people`. - name: credit_ledger_entries description: >- Registry package `mcp.playtables/credit_ledger_entries`, served on MCP mount `id.billing`. - name: data_source_items description: >- Registry package `mcp.playtables/data_source_items`, served on MCP mount `playtables.sources`. - name: data_sources description: >- Registry package `mcp.playtables/data_sources`, served on MCP mount `playtables.sources`. - name: notes description: >- Registry package `mcp.playtables/notes`, served on MCP mount `playtables.pipeline`. - name: people description: >- Registry package `mcp.playtables/people`, served on MCP mount `playtables.people`. - name: pipeline_stages description: >- Registry package `mcp.playtables/pipeline_stages`, served on MCP mount `playtables.pipeline`. - name: plays description: >- Registry package `mcp.playtables/plays`, served on MCP mount `playtables.pipeline`. - name: playtable_field_values description: >- Registry package `mcp.playtables/playtable_field_values`, served on MCP mount `playtables.columns`. - name: playtable_fields description: >- Registry package `mcp.playtables/playtable_fields`, served on MCP mount `playtables.columns`. - name: playtable_runs description: >- Registry package `mcp.playtables/playtable_runs`, served on MCP mount `playtables.columns`. - name: playtable_views description: >- Registry package `mcp.playtables/playtable_views`, served on MCP mount `playtables.tables`. - name: playtables description: >- Registry package `mcp.playtables/playtables`, served on MCP mount `playtables.tables`. - name: result_pages description: >- Registry package `mcp.playtables/result_pages`, served on MCP mount `playtables.tables`. - name: sender_profiles description: >- Registry package `mcp.playtables/sender_profiles`, served on MCP mount `playtables.sources`. - name: stoplist_entries description: >- Registry package `mcp.playtables/stoplist_entries`, served on MCP mount `playtables.stoplist`. - name: tags description: >- Registry package `mcp.playtables/tags`, served on MCP mount `playtables.pipeline`. - name: workflow_attachments description: >- Registry package `mcp.playtables/workflow_attachments`, served on MCP mount `playtables.workflows`. - name: workflow_records description: >- Registry package `mcp.playtables/workflow_records`, served on MCP mount `playtables.journeys`. - name: workflow_sources description: >- Registry package `mcp.playtables/workflow_sources`, served on MCP mount `playtables.workflows`. - name: workflow_tasks description: >- Registry package `mcp.playtables/workflow_tasks`, served on MCP mount `playtables.journeys`. - name: workflow_versions description: >- Registry package `mcp.playtables/workflow_versions`, served on MCP mount `playtables.workflows`. - name: workflows description: >- Registry package `mcp.playtables/workflows`, served on MCP mount `playtables.workflows`. paths: /api/data-sources/ai-plan: post: tags: - data_sources summary: Plan data source filters description: >- Turn a description of who to find into a wire-ready filter set without creating anything: the step before create_data_source when the user should see or edit what will be searched. Paid: the AI parse costs one credit per call. It reads the words into facets (location, industry, current and past company, school, seniority, job function, company headcount, titles as free text) and the platform pool resolves every id-bearing term; a term with no id lands in result.unresolved, never faked. Facets are ANDed and the values inside one facet ORed; there are no exclusion filters, so describe who to find, never who to leave out. A facet keeps at most 10 values: the first ten stay, the dropped terms are named in result.warnings. Hand the answer to create_data_source as is: type and object_type from the result, name = suggested_name, payload = {filters, prompt: } (find_people adds payload.company_sids). create_data_source with payload.prompt alone plans the same way at its first collect step, so call this only when the plan must be seen first. Refusals: 422 on prompt when nothing usable was read (ai_parse_failed or ai_empty_filter: rephrase with roles, places or industries); a busy pool answers 503 service_unavailable (context.reason infrastructure_unavailable or search_in_flight) or 429 rate_limited (pool_rate_limited), each with context.retry_after: wait until then, or create the source with the prompt alone and let its collector plan at the pool's pace. Contract: - MCP tool `plan_data_source_filters`, registry package `mcp.playtables/data_sources`, mount `playtables.sources`. - Operation `action`, response envelope `action`. - Flags: none. operationId: plan_data_source_filters requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PlanDataSourceFiltersRequest' responses: '200': description: '`action` success envelope.' content: application/json: schema: $ref: '#/components/schemas/PlanDataSourceFiltersResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' components: schemas: PlanDataSourceFiltersRequest: type: object description: Request body of `plan_data_source_filters`. properties: prompt: type: string minLength: 3 maxLength: 2000 description: >- Who to find, in the user's words ("CMOs at fintech companies in DACH", "heads of growth"). vertical: type: string enum: - people - company description: people (default) | company - what the search brings back. company_scoped: type: boolean description: >- Default false. true = a find_people plan: who to find inside companies selected in a grid; current companies are left out of the filter, the selection supplies them. required: - prompt PlanDataSourceFiltersResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - action action: type: string description: kebab-case verb; matches the route segment. item: {} result: type: object properties: engine: type: string description: >- Always "sales_nav": the wire engine the filters are written for; the collector runs them only under it. type: type: string enum: - ai_search - sender_search - post_engagement - find_people - csv - webhook description: >- The kind to create with this plan: ai_search for an open search, find_people for a company_scoped one. object_type: type: string enum: - people - company description: >- What the plan finds (the vertical): people | company. Pass it to create_data_source. filters: anyOf: - type: object additionalProperties: {} - type: array items: {} description: >- The wire-ready filter set: pass it verbatim as payload.filters. Different facets are ANDed and the values inside one facet ORed. Id facets ride as [{id}] (locations, industries, current_companies, past_companies, schools), the fixed lists as flat ids (seniority_levels, functions, company_headcounts), titles as [{text}] (current_titles). chips: type: array items: type: object properties: key: type: string description: >- The semantic key the term fills: titles, seniorities, functions, company_sizes, locations, industries, current_companies, past_companies, schools, keywords, network, company_types. term: type: string description: The human term as the description put it. id: type: string description: >- The facet id it resolved to; absent on a free-text facet (a title rides as text). label: type: string description: The label the search resolved for that id. required: - key - term description: >- The human reading of the same filter, one chip per term (what the product shows under "View details"). Relay these to the user before you create anything. unresolved: type: array items: type: object properties: key: type: string term: type: string required: - key - term description: >- Terms no facet id was found for: DROPPED from filters, never faked. Resolve one with suggest_data_source_filter_values and add the chosen id under the matching wire key, or tell the user the search is narrower than asked. warnings: type: array items: type: string description: Sentences worth relaying to the user. suggested_name: type: string description: >- A source name derived from the description (max 255): pass it as name. required: - engine - type - object_type - filters - chips - unresolved - warnings - suggested_name meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: string nullable: true description: >- The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: string nullable: true description: >- user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - operation - action - item - result - meta McpError: type: object properties: success: type: boolean enum: - false error: type: object properties: code: type: string enum: - validation_failed - nothing_to_update - not_found - relation_not_found - invalid_transition - limit_exceeded - payment_required - duplicate_rejected - conflict - delete_blocked - unauthorized - forbidden - rate_limited - internal_error - service_unavailable - not_implemented message: type: string recoverable: type: boolean suggestion: type: string field_errors: type: object additionalProperties: type: array items: type: object properties: rule: type: string message: type: string required: - rule - message blockers: type: array items: type: object properties: type: type: string description: >- Machine-readable blocker type (active_flow, pending_tasks, …). severity: type: string enum: - hard - soft description: >- hard = external action required; soft = acknowledge is enough. description: type: string entity_sid: type: string nullable: true count: type: integer resolution: type: string description: 'Hard: tool name to call. Soft: code for acknowledge[].' resolution_hint: type: string required: - type - severity - description - entity_sid - resolution - resolution_hint context: type: object additionalProperties: {} required: - code - message - recoverable meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: string nullable: true description: >- The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: string nullable: true description: >- user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - error responses: McpClientError: description: >- MCP error envelope. `error.code` is one of validation_failed, nothing_to_update, not_found, relation_not_found, invalid_transition, limit_exceeded, payment_required, duplicate_rejected, conflict, delete_blocked, unauthorized, forbidden, rate_limited, not_implemented. content: application/json: schema: $ref: '#/components/schemas/McpError' McpServerError: description: >- MCP error envelope with `error.code` internal_error or service_unavailable. content: application/json: schema: $ref: '#/components/schemas/McpError' securitySchemes: BearerJwt: type: http scheme: bearer bearerFormat: JWT description: >- Access token issued by gs.service.id. Its `access_identity` claim carries `team_sid`, `actor_sid` and `actor_type`, and that team scope is authoritative. TeamSid: type: apiKey in: header name: Team-SID description: >- Team scope for tokens that do not carry one. Ignored when the token already names a team. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.