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

# Partially Update A Scout

> Update specific fields of an existing Scout. Only provided fields will be updated; omitted fields remain unchanged.

<RequestExample>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url https://api.yutori.com/v1/scouting/tasks/123e4567-e89b-12d3-a456-426614174000 \
    --header 'X-API-Key: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "output_interval": 7200
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.patch(
      "https://api.yutori.com/v1/scouting/tasks/123e4567-e89b-12d3-a456-426614174000",
      headers={"X-API-Key": "YOUR_API_KEY"},
      json={"output_interval": 7200}
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.yutori.com/v1/scouting/tasks/123e4567-e89b-12d3-a456-426614174000",
    {
      method: "PATCH",
      headers: {
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ output_interval: 7200 })
    }
  );
  const data = await response.json();
  ```
</RequestExample>

## Overview

Partially update a Scout's configuration.

This is useful when you want to:

* Change a single setting without re-submitting the entire configuration
* Toggle visibility or notification settings
* Update the monitoring frequency

## Supported Fields

| Field             | Type    | Description                                      |
| ----------------- | ------- | ------------------------------------------------ |
| `query`           | string  | The monitoring query in natural language         |
| `output_interval` | integer | Seconds between outputs (minimum: 3600)          |
| `user_timezone`   | string  | Timezone string (e.g., "America/Los\_Angeles")   |
| `user_location`   | string  | Location string (e.g., "San Francisco, CA, US")  |
| `is_public`       | boolean | Whether the scout is publicly accessible         |
| `skip_email`      | boolean | Whether to skip email notifications              |
| `webhook_url`     | string  | Webhook URL for updates (empty string to remove) |

## Use Cases

### 1. Update Output Frequency

Change how often the scout runs without touching other settings:

```bash Request theme={null}
curl --request PATCH \
  --url https://api.yutori.com/v1/scouting/tasks/{scout_id} \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "output_interval": 7200
  }'
```

```json Response theme={null}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "query": "Latest news about AI startups",
  "display_name": "AI Startup News",
  "next_run_timestamp": "2024-01-15T10:00:00Z",
  "user_timezone": "America/Los_Angeles",
  "next_output_timestamp": "2024-01-15T12:00:00Z",
  "created_at": "2024-01-01T00:00:00Z",
  "completed_at": null,
  "paused_at": null,
  "is_public": true,
  "webhook_url": null
}
```

### 2. Toggle Visibility

Make a scout private or public:

```bash Request theme={null}
curl --request PATCH \
  --url https://api.yutori.com/v1/scouting/tasks/{scout_id} \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "is_public": false
  }'
```

### 3. Disable Email Notifications

Stop receiving emails while keeping the scout running:

```bash Request theme={null}
curl --request PATCH \
  --url https://api.yutori.com/v1/scouting/tasks/{scout_id} \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "skip_email": true
  }'
```

### 4. Update Multiple Fields

Change several settings at once:

```bash Request theme={null}
curl --request PATCH \
  --url https://api.yutori.com/v1/scouting/tasks/{scout_id} \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "Updated monitoring query",
    "output_interval": 14400,
    "is_public": false,
    "skip_email": true
  }'
```

### 5. Add or Update Webhook

Set up webhook notifications:

```bash Request theme={null}
curl --request PATCH \
  --url https://api.yutori.com/v1/scouting/tasks/{scout_id} \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "webhook_url": "https://your-server.com/webhook"
  }'
```

### 6. Remove Webhook

Remove webhook by setting to empty string:

```bash Request theme={null}
curl --request PATCH \
  --url https://api.yutori.com/v1/scouting/tasks/{scout_id} \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "webhook_url": ""
  }'
```

## Error Responses

### 400 Bad Request - No Fields Provided

```json theme={null}
{
  "detail": "At least one field must be provided for update"
}
```

### 400 Bad Request - Invalid Output Interval

```json theme={null}
{
  "detail": [
    {
      "type": "greater_than_equal",
      "loc": ["body", "output_interval"],
      "msg": "Input should be greater than or equal to 3600",
      "input": 1800
    }
  ]
}
```

### 400 Bad Request - Invalid Webhook URL

```json theme={null}
{
  "detail": "Invalid webhook URL"
}
```

### 403 Forbidden - Not the Creator

```json theme={null}
{
  "detail": "Only the creator of a scout can edit it"
}
```

### 404 Not Found

```json theme={null}
{
  "detail": "Scout with id {scout_id} not found"
}
```

## Notes

* Only the scout creator can use this endpoint
* Omitted fields retain their current values
* Webhook URLs must use HTTPS
* This endpoint is idempotent - safe to retry


## OpenAPI

````yaml PATCH /v1/scouting/tasks/{scout_id}
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://api.yutori.com
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /v1/scouting/tasks/{scout_id}:
    patch:
      tags:
        - Scouting
      summary: Partially update a Scout
      description: >-
        Update specific fields of an existing Scout. Only provided fields will
        be updated; omitted fields remain unchanged.
      operationId: patch_scout_v1_scouting_tasks__scout_id__patch
      parameters:
        - name: scout_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Scout Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchScoutRequestAPI'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateScoutResponsePublic'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PatchScoutRequestAPI:
      properties:
        query:
          anyOf:
            - type: string
            - type: 'null'
          title: Query
          description: String describing what to monitor in natural language
        output_interval:
          anyOf:
            - type: integer
              minimum: 1800
            - type: 'null'
          title: Output Interval
          description: Interval in seconds between outputs (must be >= 1800)
        user_timezone:
          anyOf:
            - type: string
            - type: 'null'
          title: User Timezone
          description: User's timezone (e.g. 'America/Los_Angeles')
        user_location:
          anyOf:
            - type: string
            - type: 'null'
          title: User Location
          description: User's coarse location (e.g. 'San Francisco, CA, US')
        is_public:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Public
          description: Whether the scout is publicly accessible
        skip_email:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Skip Email
          description: If true, email notifications will be skipped
        output_schema:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Output Schema
          description: >-
            JSON Schema for structured output (replaces the scout's existing
            output schema)
          examples:
            - items:
                properties:
                  headline:
                    description: News headline
                    type: string
                  summary:
                    description: Brief summary
                    type: string
                  source_url:
                    description: URL for more details
                    type: string
                type: object
              type: array
        webhook_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Webhook Url
          description: Webhook URL to receive updates (set to empty string to remove)
        webhook_format:
          anyOf:
            - type: string
              enum:
                - scout
                - slack
                - zapier
            - type: 'null'
          title: Webhook Format
          description: >-
            Webhook payload format to use when updating webhook_url. Defaults to
            'scout' when omitted. Slack incoming webhook URLs require 'slack'.
            Only takes effect when webhook_url is also provided in the same
            request.
          examples:
            - scout
      type: object
      title: PatchScoutRequestAPI
      description: |-
        Experimental: Partial update for a Scout via the Developer API.
        Only provided fields will be updated; omitted fields remain unchanged.
    CreateScoutResponsePublic:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        query:
          type: string
          title: Query
        query_object:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Query Object
        display_name:
          type: string
          title: Display Name
        next_run_timestamp:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Next Run Timestamp
        user_timezone:
          type: string
          title: User Timezone
        next_output_timestamp:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Next Output Timestamp
        created_at:
          type: string
          format: date-time
          title: Created At
        completed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Completed At
        paused_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Paused At
        rejection_reason:
          anyOf:
            - $ref: '#/components/schemas/RejectionReason'
            - type: 'null'
        is_public:
          type: boolean
          title: Is Public
          default: false
        view_url:
          anyOf:
            - type: string
            - type: 'null'
          title: View Url
          description: URL to view this scout's details in the API platform dashboard.
        webhook_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Webhook Url
          description: >-
            Optional webhook URL configured for this scout, if provided at
            creation time.
        output_schema:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Output Schema
          description: JSON Schema for structured output, if configured
          readOnly: true
      type: object
      required:
        - id
        - query
        - display_name
        - next_run_timestamp
        - user_timezone
        - next_output_timestamp
        - created_at
        - completed_at
        - paused_at
        - output_schema
      title: CreateScoutResponsePublic
      description: >-
        Public API response for scout creation. Excludes internal fields like
        llm_output.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    RejectionReason:
      type: string
      enum:
        - insufficient_prepaid_balance
        - budget_exceeded
        - subscription_inactive
      title: RejectionReason
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: x-api-key
      in: header

````