Yutori Scouting API
The Scouting API from Yutori — 16 operation(s) for scouting.
The Scouting API from Yutori — 16 operation(s) for scouting.
openapi: 3.1.0
info:
title: Fast Browsing Scouting API
version: 0.1.0
servers:
- url: https://api.yutori.com
description: Production
security:
- ApiKeyAuth: []
tags:
- name: Scouting
paths:
/v1/scouting/updates:
get:
summary: Get All Updates Api
description: Get all updates across the user's scouts within a time range.
operationId: get_all_updates_api_v1_scouting_updates_get
parameters:
- name: start_time
in: query
required: true
schema:
type: string
title: Start Time
- name: end_time
in: query
required: true
schema:
type: string
title: End Time
- name: page_size
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 1
default: 50
title: Page Size
- name: cursor
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Cursor
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/GetAllUpdatesPublicResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
tags:
- Scouting
/v1/scouting/tasks/{scout_id}/updates:
get:
summary: Get Updates Api
operationId: get_updates_api_v1_scouting_tasks__scout_id__updates_get
parameters:
- name: scout_id
in: path
required: true
schema:
type: string
format: uuid
title: Scout Id
- name: page_size
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
title: Page Size
- name: cursor
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Cursor
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/GetScoutUpdatesPublicResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
tags:
- Scouting
/v1/usage:
get:
tags:
- Scouting
summary: Get Usage
description: Get usage statistics over different time periods, active scouts, and rate limits.
operationId: get_usage_v1_usage_get
parameters:
- name: period
in: query
required: false
schema:
$ref: '#/components/schemas/TimeRange'
default: 24h
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/UsageResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/scouting/tasks:
post:
tags:
- Scouting
summary: Create Scout Task
operationId: create_scout_task_v1_scouting_tasks_post
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateScoutRequestAPI'
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'
get:
tags:
- Scouting
summary: Get Scouts
description: List scouting tasks for this user.
operationId: get_scouts_v1_scouting_tasks_get
parameters:
- name: status
in: query
required: false
schema:
anyOf:
- enum:
- active
- paused
- done
type: string
- type: 'null'
description: Filter by scout status
title: Status
description: Filter by scout status
- name: page_size
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
title: Page Size
- name: cursor
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Cursor
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ScoutListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/scouting/tasks/{scout_id}:
put:
tags:
- Scouting
summary: Edit Scout
operationId: edit_scout_v1_scouting_tasks__scout_id__put
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/EditScoutRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/Scout'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
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'
get:
tags:
- Scouting
summary: Get Scout Detail
description: Get detailed information about a specific scout owned by this user.
operationId: get_scout_detail_v1_scouting_tasks__scout_id__get
parameters:
- name: scout_id
in: path
required: true
schema:
type: string
format: uuid
title: Scout Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ScoutDetailResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Scouting
summary: Delete Scout
operationId: delete_scout_v1_scouting_tasks__scout_id__delete
parameters:
- name: scout_id
in: path
required: true
schema:
type: string
format: uuid
title: Scout Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/scouting/tasks/{scout_id}/done:
post:
tags:
- Scouting
summary: Mark Scout As Done
description: Mark a scout as done. The scout will be archived and stop running.
operationId: mark_scout_as_done_v1_scouting_tasks__scout_id__done_post
parameters:
- name: scout_id
in: path
required: true
schema:
type: string
format: uuid
title: Scout Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/scouting/tasks/{scout_id}/complete:
post:
tags:
- Scouting
summary: Mark Scout As Complete
description: '⚠️ DEPRECATED: Use POST /scouting/tasks/{scout_id}/done instead.'
operationId: mark_scout_as_complete_v1_scouting_tasks__scout_id__complete_post
deprecated: true
parameters:
- name: scout_id
in: path
required: true
schema:
type: string
format: uuid
title: Scout Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/scouting/tasks/{scout_id}/subscribe:
post:
tags:
- Scouting
summary: Subscribe
description: '⚠️ DEPRECATED: Use PUT /scouting/tasks/{scout_id}/email-settings with subscribers_to_add instead'
operationId: subscribe_v1_scouting_tasks__scout_id__subscribe_post
deprecated: true
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/CreateSubscriptionRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/scouting/tasks/{scout_id}/unsubscribe:
post:
tags:
- Scouting
summary: Unsubscribe
description: '⚠️ DEPRECATED: Use PUT /scouting/tasks/{scout_id}/email-settings with subscribers_to_remove instead'
operationId: unsubscribe_v1_scouting_tasks__scout_id__unsubscribe_post
deprecated: true
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/DeleteSubscriptionRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/scouting/tasks/{scout_id}/subscriptions:
get:
tags:
- Scouting
summary: Get Subscriptions
operationId: get_subscriptions_v1_scouting_tasks__scout_id__subscriptions_get
parameters:
- name: scout_id
in: path
required: true
schema:
type: string
format: uuid
title: Scout Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/scouting/tasks/{scout_id}/subscribe/bulk:
post:
tags:
- Scouting
summary: Bulk Subscribe
description: '⚠️ DEPRECATED: Use PUT /scouting/tasks/{scout_id}/email-settings with subscribers_to_add instead'
operationId: bulk_subscribe_v1_scouting_tasks__scout_id__subscribe_bulk_post
deprecated: true
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/BulkAddSubscribersRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/scouting/tasks/{scout_id}/pause:
post:
tags:
- Scouting
summary: Pause Scout Endpoint
operationId: pause_scout_endpoint_v1_scouting_tasks__scout_id__pause_post
parameters:
- name: scout_id
in: path
required: true
schema:
type: string
format: uuid
title: Scout Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/scouting/tasks/{scout_id}/resume:
post:
tags:
- Scouting
summary: Resume Scout Endpoint
operationId: resume_scout_endpoint_v1_scouting_tasks__scout_id__resume_post
parameters:
- name: scout_id
in: path
required: true
schema:
type: string
format: uuid
title: Scout Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/scouting/tasks/{scout_id}/restart:
post:
tags:
- Scouting
summary: Restart Scout Endpoint
operationId: restart_scout_endpoint_v1_scouting_tasks__scout_id__restart_post
parameters:
- name: scout_id
in: path
required: true
schema:
type: string
format: uuid
title: Scout Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/scouting/tasks/{scout_id}/email-settings:
put:
tags:
- Scouting
summary: Update Email Settings
description: Update email notification settings and manage subscribers for a scout.
operationId: update_email_settings_v1_scouting_tasks__scout_id__email_settings_put
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/UpdateEmailSettingsRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateEmailSettingsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/scouting/webhooks/test:
post:
tags:
- Scouting
summary: Test Webhook
operationId: test_webhook_v1_scouting_webhooks_test_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TestWebhookFormatRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
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
DeleteSubscriptionRequest:
properties:
method:
type: string
enum:
- email
- scout_webhook
- slack_webhook
- zapier_webhook
- rss
title: Method
address:
anyOf:
- type: string
- type: 'null'
title: Address
description: Webhook URL (required for webhook method)
type: object
required:
- method
title: DeleteSubscriptionRequest
SubscriberResult:
properties:
email:
type: string
title: Email
description: The email address
status:
type: string
enum:
- added
- removed
- already_subscribed
- not_found
- invalid
- permission_denied
title: Status
description: Result status for this email operation
message:
anyOf:
- type: string
- type: 'null'
title: Message
description: Additional details about the result
type: object
required:
- email
- status
title: SubscriberResult
TestWebhookFormatRequest:
properties:
webhook_url:
type: string
title: Webhook Url
description: Webhook URL to test
webhook_format:
type: string
enum:
- scout
- slack
- zapier
title: Webhook Format
description: Webhook payload format to test (use 'slack' for Slack incoming webhooks)
scout_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Scout Id
description: Optional scout ID to use for test data
type: object
required:
- webhook_url
- webhook_format
title: TestWebhookFormatRequest
UpdateEmailSettingsRequest:
properties:
skip_email:
anyOf:
- type: boolean
- type: 'null'
title: Skip Email
description: "\n If true, email notifications will be skipped and only webhook notifications will be sent.\n If false, both email and webhook notifications will be sent (default behavior).\n "
subscribers_to_add:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Subscribers To Add
description: List of email addresses to subscribe to this scout. Maximum 200 per request. Duplicates are automatically ignored.
subscribers_to_remove:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Subscribers To Remove
description: List of email addresses to unsubscribe from this scout. Non-creators can only remove themselves.
type: object
title: UpdateEmailSettingsRequest
BulkAddSubscribersRequest:
properties:
emails:
items:
type: string
type: array
title: Emails
description: List of user emails to subscribe to the scout
type: object
required:
- emails
title: BulkAddSubscribersRequest
UpdateEmailSettingsResponse:
properties:
scout_id:
type: string
title: Scout Id
description: The ID of the scout
skip_email:
anyOf:
- type: boolean
- type: 'null'
title: Skip Email
description: Current skip_email setting, if updated
subscribers_added:
anyOf:
- items:
$ref: '#/components/schemas/SubscriberResult'
type: array
- type: 'null'
title: Subscribers Added
description: Results for each email address in subscribers_to_add
subscribers_removed:
anyOf:
- items:
$ref: '#/components/schemas/SubscriberResult'
type: array
- type: 'null'
title: Subscribers Removed
description: Results for each email address in subscribers_to_remove
message:
type: string
title: Message
description: Summary of changes made
type: object
required:
- scout_id
- message
title: UpdateEmailSettingsResponse
EditScoutRequest:
properties:
query:
type: string
title: Query
description: "\n The query string includes any notification preferences in natural language.\n This is typically what the user types into the UI.\n e.g. \"Posts on r/sanfrancisco about new offices opening in downtown sf, daily at 9am\"\n Based on the user's query, we LLM-suggest 3 'when to notify' options, and the user's selection is\n translated to next_output_timestamp and output_interval.\n "
query_object:
additionalProperties: true
type: object
title: Query Object
description: Query metadata
display_name:
type: string
title: Display Name
default: ''
user_timezone:
type: string
title: User Timezone
description: "\n Automatically inferred from the client.\n E.g. \"America/Los_Angeles\"\n "
llm_output:
additionalProperties: true
type: object
title: Llm Output
description: Legacy attribute that might be removed in the future.
output_interval:
type: integer
title: Output Interval
description: "\n Interval in seconds of how often to run the task.\n For 'whenever there's an update' style Scouts, this'll be 3600 (= 1 hour).\n "
default: 7200
next_output_timestamp:
type: integer
title: Next Output Timestamp
description: "\n Unix timestamp of when the next output is expected for periodic Scouts.\n For 'whenever there's an update' style Scouts, this should be 0.\n "
default: 0
user_location:
anyOf:
- type: string
- type: 'null'
title: User Location
description: "\n The user's coarse location in the format: city, region_code, country_name.\n E.g. \"San Francisco, CA, US\"\n "
is_public:
type: boolean
title: Is Public
description: "\n Whether the scout is publicly accessible (true) or private (false).\n Public scouts can be accessed by anyone via the UUID link.\n Private scouts can only be accessed by the creator.\n "
default: true
connectors_config:
anyOf:
- $ref: '#/components/schemas/ConnectorsConfigPayload'
- type: 'null'
description: "\n Per-scout connector configuration. Controls which Composio OAuth connectors are enabled.\n - null: connectors disabled (default, opt-in model)\n - {\"enabled\": true}: all user's connectors enabled\n - {\"enabled\": false}: connectors disabled\n "
type: object
required:
- query
- query_object
- user_timezone
- llm_output
title: EditScoutRequest
GetAllUpdatesPublicResponse:
properties:
updates:
items:
$ref: '#/components/schemas/DeveloperUpdateWithScout'
type: array
title: Updates
prev_cursor:
anyOf:
- type: string
- type: 'null'
title: Prev Cursor
description: Cursor for previous page
next_cursor:
anyOf:
- type: string
- type: 'null'
title: Next Cursor
description: Cursor for next page
type: object
required:
- updates
title: GetAllUpdatesPublicResponse
description: Public API response for fetching updates across API-created scouts.
JsonSchemaSpec:
properties:
type:
type: string
const: json
title: Type
default: json
json_schema:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Json Schema
description: A JSON Schema object defining the structure
type: object
title: JsonSchemaSpec
ScoutListItem:
properties:
id:
type: string
format: uuid
title: Id
query:
type: string
title: Query
display_name:
type: string
title: Display Name
status:
type: string
enum:
- active
- paused
- done
title: Status
created_at:
type: string
format: date-time
title: Created At
next_output_timestamp:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Next Output Timestamp
output_interval:
type: integer
title: Output Interval
description: Run interval in seconds
rejection_reason:
anyOf:
- $ref: '#/components/schemas/RejectionReason'
- type: 'null'
type: object
required:
- id
- query
- display_name
- status
- created_at
- next_output_timestamp
- output_interval
title: ScoutListItem
description: Lightweight scout metadata for list endpoints.
TimeRange:
type: string
enum:
- 24h
- 7d
- 30d
- 90d
title: TimeRange
CreateSubscriptionRequest:
properties:
method:
type: string
enum:
- email
- scout_webhook
- slack_webhook
- zapier_webhook
- rss
title: Method
address:
anyOf:
- type: string
- type: 'null'
title: Address
description: Webhook URL (required for webhook method)
type: object
required:
- method
title: CreateSubscriptionRequest
ActivityCounts:
properties:
period:
type: string
enum:
- 24h
- 7d
- 30d
- 90d
title: Period
scout_runs:
type: integer
title: Scout Runs
browsing_tasks:
type: integer
title: Browsing Tasks
research_tasks:
type: integer
title: Research Tasks
navigator_calls:
type: integer
title: Navigator Calls
description: Navigator (chat completions) calls in period
n1_calls:
type: integer
title: N1 Calls
description: Deprecated alias of navigator_calls; prefer navigator_calls
deprecated: true
readOnly: true
type: object
required:
- period
- scout_runs
- browsing_tasks
- research_tasks
- navigator_calls
- n1_calls
title: ActivityCounts
ScoutDetailResponse:
properties:
id:
type: string
format: uuid
title: Id
query:
type: string
title: Query
display_name:
type: string
title: Display Name
status:
type: string
enum:
- active
- paused
- done
title: Status
created_at:
type: string
format: date-time
title: Created At
next_run_timestamp:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Next Run Timestamp
next_output_timestamp:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Next Output Timestamp
user_timezone:
type: string
title: User Timezone
output_interval:
type: integer
title: Output Interval
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'
last_update_timestamp:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Update Timestamp
update_count:
type: integer
title: Update Count
query_object:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Query Object
is_public:
type: boolean
title: Is Public
default: true
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
- status
- created_at
- next_run_timestamp
- next_output_timestamp
- user_timezone
- output_interval
- completed_at
- paused_at
- last_update_timestamp
- update_count
- output_schema
title: ScoutDetailResponse
description: Detailed scout information for detail endpoint.
ConnectorsConfig:
properties:
enabled:
type: boolean
title: Enabled
description: Whether connectors are enabled for this scout
type: object
required:
- enabled
title: ConnectorsConfig
TaskSpec:
properties:
output_schema:
anyOf:
- $ref: '#/components/schemas/JsonSchemaSpec'
- type: 'null
# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/yutori/refs/heads/main/openapi/yutori-scouting-api-openapi.yml