---
title: "Create A Task"
method: POST
path: "/v1/research/tasks"
tags: ["Research"]
---

# Create A Task

`POST /v1/research/tasks`

## Request

- Base URL: `https://api.yutori.com`
- URL: `https://api.yutori.com/v1/research/tasks`
- Auth: API key in header `x-api-key`

Launches a one-time research task on the web.

## Request body

- CreateResearchTaskRequest
  - `output_schema` object, nullable: JSON Schema for structured output. Takes precedence over task_spec if both provided.
  - `task_spec` TaskSpec
    - `output_schema` JsonSchemaSpec
      - `type` 'json'
      - `json_schema` object, nullable: A JSON Schema object defining the structure
  - `used_deprecated_task_spec` boolean
  - `query` string, required: String describing the research task in natural language.
  - `user_timezone` string: User's timezone for contextual awareness (e.g. 'America/Los_Angeles')
  - `user_location` string, nullable: User's coarse location in the format: city, region_code, country_name
  - `skip_email` boolean: If true, email notifications will be skipped and only webhook notifications will be sent. Default: true (sends webhooks only).
  - `webhook_url` string, nullable: Optional webhook URL to receive results when the research task completes
  - `webhook_format` 'scout' | 'slack' | 'zapier': Webhook payload format. Slack incoming webhook URLs require 'slack'.

## Response `200`

Successful Response

- CreateResearchTaskResponse: Response for creating a research task.
  - `task_id` string, required: Unique identifier for this research task
  - `view_url` string, required: URL to view task progress and results
  - `status` 'queued' | 'running' | 'succeeded' | 'failed', required: Current status of the research task
  - `webhook_url` string, nullable: Echoes the webhook URL configured for this task, if provided

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/yutori/apis/yutori-api.md) - [All operations](https://skmtc.dev/yutori/apis/yutori-api/llms.txt) - [OpenAPI document](https://skmtc.dev/yutori/apis/yutori-api/revisions/ef669f82d5bc?raw)