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

# Create A Task

> Launches a one-time research task on the web.

```bash cURL theme={null}
curl --request POST \
  --url https://api.yutori.com/v1/research/tasks \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "What are the latest developments in quantum computing from the past week? Include company announcements, research papers, and product releases."
  }'
```

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

response = requests.post(
    "https://api.yutori.com/v1/research/tasks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "query": "What are the latest developments in quantum computing from the past week? Include company announcements, research papers, and product releases."
    }
)
print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.yutori.com/v1/research/tasks", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    query: "What are the latest developments in quantum computing from the past week? Include company announcements, research papers, and product releases."
  })
});
const data = await response.json();
```

## Advanced Example

> [accordion] Receive structured output on a webhook when the task completes
>
> Configure structured output with `output_schema` to receive data in a specific JSON schema format, and optionally add webhook notifications.
>
> ```bash cURL theme={null}
> curl --request POST \
>   --url https://api.yutori.com/v1/research/tasks \
>   --header 'X-API-Key: YOUR_API_KEY' \
>   --header 'Content-Type: application/json' \
>   --data '{
>     "query": "What are the latest developments in quantum computing from the past week? Include company announcements, research papers, and product releases.",
>     "user_timezone": "America/Los_Angeles",
>     "webhook_url": "https://example.com/webhook",
>     "output_schema": {
>       "type": "array",
>       "items": {
>         "type": "object",
>         "properties": {
>           "title": { "type": "string" },
>           "summary": { "type": "string" },
>           "source_url": { "type": "string" }
>         }
>       }
>     }
>   }'
> ```
>
> ```python Python theme={null}
> import requests
>
> response = requests.post(
>     "https://api.yutori.com/v1/research/tasks",
>     headers={"X-API-Key": "YOUR_API_KEY"},
>     json={
>         "query": "What are the latest developments in quantum computing from the past week? Include company announcements, research papers, and product releases.",
>         "user_timezone": "America/Los_Angeles",
>         "webhook_url": "https://example.com/webhook",
>         "output_schema": {
>             "type": "array",
>             "items": {
>                 "type": "object",
>                 "properties": {
>                     "title": {"type": "string"},
>                     "summary": {"type": "string"},
>                     "source_url": {"type": "string"}
>                 }
>             }
>         }
>     }
> )
> print(response.json())
> ```
>
> ```javascript JavaScript theme={null}
> const response = await fetch("https://api.yutori.com/v1/research/tasks", {
>   method: "POST",
>   headers: {
>     "X-API-Key": "YOUR_API_KEY",
>     "Content-Type": "application/json"
>   },
>   body: JSON.stringify({
>     query: "What are the latest developments in quantum computing from the past week? Include company announcements, research papers, and product releases.",
>     user_timezone: "America/Los_Angeles",
>     webhook_url: "https://example.com/webhook",
>     output_schema: {
>       type: "array",
>       items: {
>         type: "object",
>         properties: {
>           title: { type: "string" },
>           summary: { type: "string" },
>           source_url: { type: "string" }
>         }
>       }
>     }
>   })
> });
> const data = await response.json();
> ```


## OpenAPI

````yaml POST /v1/research/tasks
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://api.yutori.com
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /v1/research/tasks:
    post:
      tags:
        - Research
      summary: Create A Task
      description: Launches a one-time research task on the web.
      operationId: create_research_task_v1_research_tasks_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateResearchTaskRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateResearchTaskResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CreateResearchTaskRequest:
      properties:
        output_schema:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Output Schema
          description: >-
            JSON Schema for structured output. Takes precedence over task_spec
            if both provided.
          examples:
            - items:
                properties:
                  title:
                    description: Title of the development
                    type: string
                  summary:
                    description: Brief summary
                    type: string
                  source_url:
                    description: URL for more details
                    type: string
                type: object
              type: array
        task_spec:
          anyOf:
            - $ref: '#/components/schemas/TaskSpec'
            - type: 'null'
          description: Deprecated but still supported. Use output_schema instead.
          deprecated: true
        used_deprecated_task_spec:
          type: boolean
          title: Used Deprecated Task Spec
          default: false
          hidden: true
        query:
          type: string
          title: Query
          description: |2-

                    String describing the research task in natural language.
                    
          examples:
            - >-
              What are the latest developments in quantum computing from the
              past week?
        user_timezone:
          type: string
          title: User Timezone
          description: >-
            User's timezone for contextual awareness (e.g.
            'America/Los_Angeles')
          default: America/Los_Angeles
          examples:
            - America/Los_Angeles
        user_location:
          anyOf:
            - type: string
            - type: 'null'
          title: User Location
          description: >-
            User's coarse location in the format: city, region_code,
            country_name
          default: San Francisco, CA, US
          examples:
            - San Francisco, CA, US
        skip_email:
          type: boolean
          title: Skip Email
          description: |2-

                    If true, email notifications will be skipped and only webhook notifications will be sent.
                    Default: true (sends webhooks only).
                    
          default: true
          examples:
            - true
        webhook_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Webhook Url
          description: >-
            Optional webhook URL to receive results when the research task
            completes
          examples:
            - https://example.com/webhook
        webhook_format:
          type: string
          enum:
            - scout
            - slack
            - zapier
          title: Webhook Format
          description: Webhook payload format. Slack incoming webhook URLs require 'slack'.
          default: scout
          examples:
            - scout
      type: object
      required:
        - query
      title: CreateResearchTaskRequest
    CreateResearchTaskResponse:
      properties:
        task_id:
          type: string
          title: Task Id
          description: Unique identifier for this research task
        view_url:
          type: string
          title: View Url
          description: URL to view task progress and results
        status:
          type: string
          enum:
            - queued
            - running
            - succeeded
            - failed
          title: Status
          description: Current status of the research task
        webhook_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Webhook Url
          description: Echoes the webhook URL configured for this task, if provided
      type: object
      required:
        - task_id
        - view_url
        - status
      title: CreateResearchTaskResponse
      description: Response for creating a research task.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TaskSpec:
      properties:
        output_schema:
          anyOf:
            - $ref: '#/components/schemas/JsonSchemaSpec'
            - type: 'null'
      type: object
      title: TaskSpec
    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
    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
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: x-api-key
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.