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

# Create a Task - Make Voice AI Call

> Create a new task in a space to trigger a Voice AI outbound call

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://unpod.ai/api/v2/platform/spaces/{space_token}/tasks/create/ \
    --header 'Authorization: Token <api-key>' \
    --header 'Content-Type: application/json' \
    --header 'Org-Handle: <org-handle>' \
    --data '{
      "pilot": "space-agent-f1o3qjm1y7q1avvuynv4vprb1",
      "context": "Call the lead and discuss the project requirements.",
      "schedule": { "type": "now" },
      "documents": [
        {
          "name": "John Doe",
          "email": "john@example.com",
          "contact_number": "1234567890",
          "alternate_number": "+919876543210",
          "occupation": "Sales Manager",
          "company_name": "Acme Corp",
          "address": "123 Main St, Mumbai",
          "about": "Warm lead from webinar",
          "context": "Follow up on proposal sent last week",
          "labels": ["warm-lead", "webinar"],
          "title": "Q1 Outreach",
          "description": "Lead from Q1 campaign",
          "document_id": "6902fb5840a736e125e80ebc"
        }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response (200) theme={null}
  {
    "status_code": 200,
    "message": "Task Created Successfully",
    "data": {
      "run_id": "R74802366fe9011f0878d43cd8a99e069",
      "task_ids": [
        "T74802367fe9011f0878d43cd8a99e069"
      ],
      "status": "pending"
    }
  }
  ```

  ```json Error Response (206) theme={null}
  {
    "message": "Task creation failed",
    "errors": "Detailed error description"
  }
  ```
</ResponseExample>

# Create a Task - Make Voice AI Call

Create a new task inside a given space using the space's public token. You can assign the task to a pilot/agent, attach multiple documents (contacts), provide additional context, and schedule the execution.

<Note>
  **Prerequisites:** Make sure you have your API Token, Space Token, and Agent Handle ready. See [Authentication](/api/get-started/authentication) for details.
</Note>

### Endpoint

```
POST /api/v2/platform/spaces/{space_token}/tasks/create/
```

### Path Parameters

<ParamField path="space_token" type="string" required>
  Public token of the space where the task is created.
  <Note>Get this from the [Get All Spaces](/api/space/get-all-spaces) API - use the `token` field.</Note>
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>
  API Key in format: `Token <your-api-token>`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

### Request Body

<ParamField body="pilot" type="string" required>
  Agent/pilot handle to assign the task to.
</ParamField>

<ParamField body="documents" type="array" required>
  Array of document/contact objects. Each document represents one contact to call.

  <Expandable title="Document Object Fields">
    <ParamField body="name" type="string" required>
      Contact name
    </ParamField>

    <ParamField body="contact_number" type="string" required>
      Primary contact phone number
    </ParamField>

    <ParamField body="email" type="string">
      Contact email address
    </ParamField>

    <ParamField body="alternate_number" type="string">
      Alternate contact phone number
    </ParamField>

    <ParamField body="occupation" type="string">
      Contact's occupation
    </ParamField>

    <ParamField body="company_name" type="string">
      Contact's company name
    </ParamField>

    <ParamField body="address" type="string">
      Contact's address
    </ParamField>

    <ParamField body="about" type="string">
      Additional info about the contact
    </ParamField>

    <ParamField body="context" type="string">
      Per-contact context for the call
    </ParamField>

    <ParamField body="labels" type="array">
      Labels/tags associated with the record
    </ParamField>

    <ParamField body="title" type="string">
      Document title
    </ParamField>

    <ParamField body="description" type="string">
      Document description
    </ParamField>

    <ParamField body="document_id" type="string">
      Unique document identifier
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="context" type="string">
  Additional context/objective for the task (applies to all contacts).
</ParamField>

<ParamField body="schedule" type="object">
  Schedule configuration. Example: `{"type": "now"}`
</ParamField>

### Response Fields

<ResponseField name="status_code" type="integer">
  HTTP status code
</ResponseField>

<ResponseField name="message" type="string">
  Response message
</ResponseField>

<ResponseField name="data" type="object">
  Created task details

  <Expandable title="Data Object Fields">
    <ResponseField name="run_id" type="string">
      Created run identifier - use this to track execution via [Get All Runs](/api/execution/get-all-runs)
    </ResponseField>

    <ResponseField name="task_ids" type="array">
      Array of created task identifiers (one per document/contact)
    </ResponseField>

    <ResponseField name="status" type="string">
      Task status - initially `pending`
    </ResponseField>
  </Expandable>
</ResponseField>

## Common Error Codes

| Status Code | Description                                     |
| ----------- | ----------------------------------------------- |
| 200         | Success - Task created successfully             |
| 206         | Partial Content - Business logic error occurred |
| 400         | Bad Request - Invalid parameters provided       |
| 401         | Unauthorized - Invalid or missing API token     |
| 403         | Forbidden - Access denied to the resource       |
| 404         | Not Found - Space or Agent not found            |
| 500         | Internal Server Error - Server-side error       |

## Code Examples

<CodeGroup>
  ```javascript Node.js theme={null}
  const axios = require('axios');

  const headers = {
    'Authorization': 'Token your-api-token',
    'Content-Type': 'application/json'
  };

  // Create a task to make a Voice AI call
  const createTask = async (spaceToken, pilot, documents, context) => {
    const response = await axios.post(
      `https://unpod.ai/api/v2/platform/spaces/${spaceToken}/tasks/create/`,
      {
        pilot,
        documents,
        context,
        schedule: { type: 'now' }
      },
      { headers }
    );
    console.log(`Run ID: ${response.data.data.run_id}`);
    console.log(`Task IDs: ${response.data.data.task_ids.join(', ')}`);
    return response.data.data;
  };

  // Example usage
  createTask(
    '8KZAMRAHSXXXXXXMAYNASMJC',
    'space-agent-f1o3qjm1y7q1avvuynv4vprb1',
    [
      {
        name: 'John Doe',
        contact_number: '1234567890',
        email: 'john@example.com',
        context: 'Follow up on proposal'
      }
    ],
    'Call the lead and discuss the project requirements.'
  );
  ```

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

  headers = {
      'Authorization': 'Token your-api-token',
      'Content-Type': 'application/json'
  }

  def create_task(space_token: str, pilot: str, documents: list, context: str):
      """Create a Voice AI call task in a space"""
      url = f'https://unpod.ai/api/v2/platform/spaces/{space_token}/tasks/create/'
      payload = {
          'pilot': pilot,
          'documents': documents,
          'context': context,
          'schedule': {'type': 'now'}
      }
      response = requests.post(url, headers=headers, json=payload)
      data = response.json()
      print(f"Run ID: {data['data']['run_id']}")
      print(f"Task IDs: {', '.join(data['data']['task_ids'])}")
      return data['data']

  # Example usage
  create_task(
      space_token='8KZAMRAHSXXXXXXMAYNASMJC',
      pilot='space-agent-f1o3qjm1y7q1avvuynv4vprb1',
      documents=[
          {
              'name': 'John Doe',
              'contact_number': '1234567890',
              'email': 'john@example.com',
              'context': 'Follow up on proposal'
          }
      ],
      context='Call the lead and discuss the project requirements.'
  )
  ```

  ```bash cURL theme={null}
  # Create a task to trigger a Voice AI call
  curl -X POST "https://unpod.ai/api/v2/platform/spaces/8KZAMRAHSXXXXXXMAYNASMJC/tasks/create/" \
    -H "Authorization: Token your-api-token" \
    -H "Content-Type: application/json" \
    -d '{
      "pilot": "space-agent-f1o3qjm1y7q1avvuynv4vprb1",
      "documents": [
        {
          "name": "John Doe",
          "contact_number": "1234567890",
          "email": "john@example.com",
          "context": "Follow up on proposal",
          "document_id": "6902fb5840a736e125e80ebc"
        }
      ],
      "context": "Call the lead and discuss the project requirements.",
      "schedule": {"type": "now"}
    }'
  ```
</CodeGroup>

## Best Practices

1. **Pilot Handle**: Use the correct agent handle from the [Get All Agents](/api/agent/get-all-agents) API
2. **contact\_number**: Always include a valid `contact_number` in each document - this is required for call execution
3. **Batch Calls**: Pass multiple documents in the `documents` array to trigger batch calls in a single request
4. **Context**: Provide clear, specific context to guide the agent's conversation objectives
5. **Run ID**: Store the returned `run_id` to track task execution status using the [Get All Runs](/api/execution/get-all-runs) API
6. **Security**: Keep API tokens secure and rotate them regularly


## OpenAPI

````yaml POST /api/v2/platform/spaces/{space_token}/tasks/create/
openapi: 3.0.3
info:
  title: Unpod API
  description: REST API for Unpod Voice AI Platform
  version: 2.0.0
servers:
  - url: https://unpod.ai/
    description: QA
  - url: https://unpod.ai/
    description: Production
security: []
tags:
  - name: Organisation
  - name: Spaces
  - name: Agents
  - name: Tasks
  - name: Runs
  - name: Call Logs
  - name: Analytics
  - name: Providers
  - name: Bridges
  - name: Numbers
  - name: Trunks
  - name: Telephony
  - name: Billing
paths:
  /api/v2/platform/spaces/{space_token}/tasks/create/:
    post:
      tags:
        - Tasks
      summary: Create a Task - Make Voice AI Call
      operationId: createTask
      parameters:
        - name: space_token
          in: path
          required: true
          schema:
            type: string
            example: 8KZAMRAHSXXXXXXMAYNASMJC
        - $ref: '#/components/parameters/OrgHandle'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - pilot
                - documents
              properties:
                pilot:
                  type: string
                  description: Agent/pilot handle to assign the task
                  example: space-agent-f1o3qjm1y7q1avvuynv4vprb1
                documents:
                  type: array
                  description: Array of contact/document objects
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        example: John Doe
                      email:
                        type: string
                        example: john@example.com
                      contact_number:
                        type: string
                        example: '1234567890'
                      alternate_number:
                        type: string
                        example: '+919876543210'
                      occupation:
                        type: string
                        example: Sales Manager
                      company_name:
                        type: string
                        example: Acme Corp
                      address:
                        type: string
                        example: 123 Main St, Mumbai
                      about:
                        type: string
                        example: Warm lead from webinar
                      context:
                        type: string
                        example: Follow up on proposal sent last week
                      labels:
                        type: array
                        items:
                          type: string
                        example:
                          - warm-lead
                          - webinar
                      title:
                        type: string
                        example: Q1 Outreach
                      description:
                        type: string
                        example: Lead from Q1 campaign
                      document_id:
                        type: string
                        example: 6902fb5840a736e125e80ebc
                context:
                  type: string
                  description: Additional context for the task
                  example: Call the lead and discuss the project requirements.
                schedule:
                  type: object
                  description: Schedule configuration
                  example:
                    type: now
            example:
              pilot: space-agent-f1o3qjm1y7q1avvuynv4vprb1
              context: Call the lead and discuss the project requirements.
              schedule:
                type: now
              documents:
                - name: John Doe
                  email: john@example.com
                  contact_number: '1234567890'
                  alternate_number: '+919876543210'
                  occupation: Sales Manager
                  company_name: Acme Corp
                  address: 123 Main St, Mumbai
                  about: Warm lead from webinar
                  context: Follow up on proposal sent last week
                  labels:
                    - warm-lead
                    - webinar
                  title: Q1 Outreach
                  description: Lead from Q1 campaign
                  document_id: 6902fb5840a736e125e80ebc
      responses:
        '200':
          description: Task created successfully
          content:
            application/json:
              example:
                status_code: 200
                message: Task Created Successfully
                data:
                  run_id: R74802366fe9011f0878d43cd8a99e069
                  task_ids:
                    - T74802367fe9011f0878d43cd8a99e069
                  status: pending
        '206':
          description: Partial Content - Business logic error
          content:
            application/json:
              example:
                message: Task creation failed
                errors: Detailed error description
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - TokenAuth: []
components:
  parameters:
    OrgHandle:
      name: Org-Handle
      in: header
      required: true
      schema:
        type: string
        example: unpod.tv
      description: Organization domain handle
  responses:
    Unauthorized:
      description: Unauthorized - Invalid or missing API token
      content:
        application/json:
          example:
            status_code: 401
            message: Authentication credentials were not provided.
  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Format: Token <your-api-key>'

````