> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instaview.sk/llms.txt
> Use this file to discover all available pages before exploring further.

# Patch Sourcing Run

> Patches the reasoning context and/or candidate limit of an existing sourcing session and triggers a new background run. Returns 409 if a run is already in progress. At least one of query or limit must be provided.

Refines an existing sourcing session by patching the reasoning context and/or requesting additional candidates. Triggers a new background run and returns `202 Accepted`.

## Overview

After a sourcing run completes you can iterate on it — tighten or relax criteria, prioritize different signals, or harvest more candidates from the same discovered pool. The agent incorporates the new `query` as a context patch before evaluating additional profiles.

<Warning>
  **Sequential Execution Constraint**: A PATCH request is only accepted once the current run has a `status` of `"completed"` or `"failed"`. If the run is still `"processing"`, the API returns `409 Conflict`.
</Warning>

## Request Body

At least one of `query` or `limit` must be provided. Both fields may be combined in a single request.

| Field   | Type     | Required          | Description                                                                                                                   |
| ------- | -------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `query` | `string` | No (one required) | Natural language instruction to patch into the session context. Max 500 chars.                                                |
| `limit` | `number` | No (one required) | Number of **additional** candidates to evaluate (default: 10, max: 50). Profiles already scored in this session are excluded. |

## Examples

### Prompt Refinement Only

```json theme={null}
{
  "query": "Relax experience requirement from 8 years to 5 years, but prioritize candidates with strong open-source GitHub portfolios."
}
```

### Request Additional Candidates Only

```json theme={null}
{
  "limit": 15
}
```

### Combined Refinement + Additional Candidates

```json theme={null}
{
  "query": "Focus on startup founders with Kubernetes orchestration experience at Series A/B companies.",
  "limit": 5
}
```

The agent applies the `query` as an updated context patch first, then evaluates `5` additional profiles against the refined criteria — all in a single asynchronous reasoning pass.

## Response (202 Accepted)

```json theme={null}
{
  "success": true,
  "requestId": "req_9f3b827e-8c31-4bda-a7a2-b2d99d14f4e2",
  "status": "processing",
  "message": "Sourcing re-run accepted and queued for processing.",
  "updatedAt": "2026-05-20T13:21:12.000Z"
}
```

## Error Responses

### 400 — Both Fields Omitted

```json theme={null}
{
  "statusCode": 400,
  "error": "INVALID_PATCH_PAYLOAD",
  "message": "Validation failed: You must provide at least one of 'query' or 'limit'."
}
```

### 409 — Run Still In Progress

```json theme={null}
{
  "statusCode": 409,
  "error": "RUN_IN_PROGRESS",
  "message": "Sourcing agent run 'req_9f3b827e-…' is currently in progress. You can only patch the run context after the current execution finishes."
}
```


## OpenAPI

````yaml PATCH /sourcing/{id}
openapi: 3.0.0
info:
  title: InstaView API
  description: |-
    InstaView API Documentation

    ## Authentication

    All endpoints require API key authentication using Bearer token:
    ```
    Authorization: Bearer sk_your_api_key_here
    ```

    ## API Key Management

    The API Key module provides comprehensive key management for:
    - **Direct Client Keys**: Company-scoped keys for your applications
    - **ATS Partner Keys**: Resource-scoped keys for ATS integrations

    ### Key Features
    - HMAC-SHA256 hashing for API key storage
    - Configurable rate limiting
    - Comprehensive audit logging
    - Company-level isolation
    - Resource scoping for ATS partners
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.instaview.sk
    description: Production API Gateway
security: []
tags: []
paths:
  /sourcing/{id}:
    patch:
      tags:
        - Public Sourcing
      summary: Patch sourcing run
      description: >-
        Patches the reasoning context and/or candidate limit of an existing
        sourcing session and triggers a new background run. Returns 409 if a run
        is already in progress. At least one of query or limit must be provided.
      operationId: PublicSourcingController_patchSourcing_v1
      parameters:
        - name: id
          required: true
          in: path
          description: The requestId returned by POST /sourcing (e.g. req_550e8400-…).
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicPatchSourcingDto'
      responses:
        '202':
          description: Sourcing re-run accepted and queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSourcingInitiatedResponseDto'
        '400':
          description: Bad Request - Both query and limit omitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Insufficient scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found - Sourcing run not found or belongs to another company
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict - Sourcing run is still in progress
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearer: []
components:
  schemas:
    PublicPatchSourcingDto:
      type: object
      properties:
        query:
          type: string
          description: >-
            New free-text search query for the re-run. At least one of query or
            limit must be supplied.
          example: Senior Node.js engineer fintech remote
          maxLength: 500
        limit:
          type: integer
          description: >-
            Number of additional candidates to evaluate in this re-run (default:
            10, max: 50). At least one of query or limit must be supplied.
          example: 10
          minimum: 1
          maximum: 50
          default: 10
    PublicSourcingInitiatedResponseDto:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the request was accepted for processing.
          example: true
        requestId:
          type: string
          description: Unique external identifier for this sourcing run.
          example: req_550e8400-e29b-41d4-a716-446655440000
        status:
          type: string
          description: Current status of the run.
          enum:
            - processing
            - completed
            - failed
          example: processing
        message:
          type: string
          description: Human-readable message.
          example: Sourcing run accepted and queued for processing.
        webhookId:
          type: string
          description: >-
            UUID of the webhook configuration that will receive completion
            events.
          example: 123e4567-e89b-12d3-a456-426614174000
        createdAt:
          type: string
          description: ISO 8601 timestamp when the run was created (POST only).
          example: '2025-01-01T00:00:00.000Z'
        updatedAt:
          type: string
          description: ISO 8601 timestamp when the run was last updated (PATCH only).
          example: '2025-01-01T00:01:00.000Z'
      required:
        - success
        - requestId
        - status
        - message
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          example: 400
        message:
          type: string
          example: Validation failed
        error:
          type: string
          example: Bad Request
      required:
        - statusCode
        - message
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: API key for authentication using Bearer scheme

````