> ## Documentation Index > Fetch the complete documentation index at: https://docs.revcenter.ai/llms.txt > Use this file to discover all available pages before exploring further. # Run a search > Creates a search and starts the pipeline. Returns immediately with a `scanId` — the run continues in the background, so poll `GET /api/scans/{id}` for status and results. A target count written into `rawInput` ("find 25") is parsed out and used as the run's target. ## OpenAPI ````yaml /openapi.json post /api/scans openapi: 3.1.0 info: title: Revcenter API description: >- Search, enrich, and activate people and companies. Two authentication surfaces share one host: the bearer-token API under `/v1` for server-to-server and agent use, and the workspace-session API under `/api` that the Revcenter app itself runs on. version: '2026-08-12' servers: - url: https://api.revcenter.ai description: Production security: - bearerAuth: [] tags: - name: Search description: Web search, search runs, results, exports, and shareable shortlists. - name: People description: Person search, profile enrichment, and the workspace contact pool. - name: Companies description: Company search, company enrichment, and org-chart people. - name: Campaigns description: Plan, publish, and launch outbound sequences on Smartlead and HeyReach. - name: Account description: Health, usage totals, and cost events. paths: /api/scans: post: tags: - Search summary: Run a search description: >- Creates a search and starts the pipeline. Returns immediately with a `scanId` — the run continues in the background, so poll `GET /api/scans/{id}` for status and results. A target count written into `rawInput` ("find 25") is parsed out and used as the run's target. operationId: createScan requestBody: required: true content: application/json: schema: type: object required: - criteria properties: criteria: $ref: '#/components/schemas/Criteria' rawInput: type: string description: >- The original brief. Kept for provenance and parsed for a target count. mode: $ref: '#/components/schemas/ScanMode' projectId: type: - string - 'null' description: >- Attach the run to a client project so its context and disqualifiers apply. responses: '201': description: The run was created and is executing. content: application/json: schema: type: object properties: scanId: type: string format: uuid ontologyPlan: type: - object - 'null' additionalProperties: true '400': $ref: '#/components/responses/AppBadRequest' '401': $ref: '#/components/responses/AppUnauthorized' '404': $ref: '#/components/responses/AppNotFound' '424': $ref: '#/components/responses/AppProviderUnavailable' security: - sessionCookie: [] components: schemas: Criteria: type: object description: >- The structured brief a search runs on. Every field is optional, but a search with no signal finds nothing useful. The distinction that matters: `exclude_*` fields are hard and disqualify, while `avoid_*` fields are soft and only rank down. A great person at a firm you'd rather avoid still shows up; a person at an excluded firm never does. properties: family: type: string description: >- Role family from the taxonomy. Off-taxonomy roles are kept as a title variant instead. title_variants: type: array items: type: string description: >- Acceptable job titles. A quoted `title: "X"` in the brief always survives extraction and leads this list. seniority: type: string enum: - c_suite - vp - director - manager - ic allowed_seniority: type: array items: type: string enum: - c_suite - vp - director - manager - ic must_have: type: array items: type: string industries: type: array items: type: string metro: type: string examples: - San Jose, CA geo_radius_mi: type: number exclusiveMinimum: 0 description: >- Commute radius. Dropped automatically on country-level searches, where it is meaningless. remote_ok: type: boolean exclude_titles: type: array items: type: string description: Hard exclusion. exclude_industries: type: array items: type: string description: Hard exclusion. exclude_companies: type: array items: type: string description: >- Hard exclusion. Evaluated against search text too, so excluded people never reach paid enrichment. avoid_titles: type: array items: type: string description: Soft negative — ranks down, never rejects. avoid_industries: type: array items: type: string description: Soft negative. avoid_companies: type: array items: type: string description: Soft negative. comp_band: type: array items: type: number minItems: 2 maxItems: 2 years_experience: type: object properties: min: type: number max: type: number min_avg_tenure_years: type: number exclusiveMinimum: 0 skills: type: array items: type: string skills_required: type: array items: type: string languages_required: type: array items: type: string description: >- Hard requirement, kept separate from skills: holding a job title implies its competencies, but never implies a language. target_company_profile: type: object properties: sector: type: string employee_range: type: array items: type: number minItems: 2 maxItems: 2 pe_backed_preferred: type: boolean rubric_weights: type: object description: >- Relative emphasis per scoring dimension, compiled from what this brief stresses and locked to the run. The scorer clamps and renormalizes. properties: title: type: number years: type: number skills: type: number geo: type: number industry: type: number seniority: type: number ScanMode: type: string enum: - candidate - client default: candidate description: >- `candidate` searches for people against a role. `client` discovers target companies first, then their decision-makers. AppError: type: object description: >- The error shape used by every `/api` endpoint. Flatter than the `/v1` shape, and `code` appears only where the UI branches on it. properties: error: type: string code: type: string examples: - search_unavailable responses: AppBadRequest: description: Missing or invalid input. content: application/json: schema: $ref: '#/components/schemas/AppError' examples: missing: value: error: criteria (CriteriaV2) is required AppUnauthorized: description: >- Not signed in, no active workspace, or the account lacks the role this action needs. A frozen account gets `403` with code `frozen`. content: application/json: schema: $ref: '#/components/schemas/AppError' examples: signIn: value: error: Sign in required AppNotFound: description: >- The record does not exist, or belongs to another workspace. The two are deliberately indistinguishable. content: application/json: schema: $ref: '#/components/schemas/AppError' examples: notFound: value: error: Scan not found AppProviderUnavailable: description: >- A capability this action needs is not connected for the workspace. The `code` names which one. content: application/json: schema: $ref: '#/components/schemas/AppError' examples: search: value: error: Search is unavailable for this workspace. code: search_unavailable scoring: value: error: AI scoring is unavailable for this workspace. code: ai_scoring_unavailable heyreach: value: error: No HeyReach API key configured — add one in Credentials. code: heyreach_not_configured securitySchemes: bearerAuth: type: http scheme: bearer description: >- A Revcenter API key: `Authorization: Bearer rvc_live_...`. Keys are scoped, rate limited per key, and metered per workspace. sessionCookie: type: apiKey in: cookie name: session description: >- A signed-in workspace session, sent as a browser cookie. Requests must include credentials, and act on the session's active workspace. ````