Skip to main content
POST
/
api
/
v2
/
platform
/
spaces
/
{space_token}
/
tasks
/
create
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"
      }
    ]
  }'

{
  "status_code": 200,
  "message": "Task Created Successfully",
  "data": {
    "run_id": "R74802366fe9011f0878d43cd8a99e069",
    "task_ids": [
      "T74802367fe9011f0878d43cd8a99e069"
    ],
    "status": "pending"
  }
}

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"
      }
    ]
  }'

{
  "status_code": 200,
  "message": "Task Created Successfully",
  "data": {
    "run_id": "R74802366fe9011f0878d43cd8a99e069",
    "task_ids": [
      "T74802367fe9011f0878d43cd8a99e069"
    ],
    "status": "pending"
  }
}

​
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.
Prerequisites: Make sure you have your API Token, Space Token, and Agent Handle ready. See Authentication for details.

​
Endpoint

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

​
Path Parameters

​
space_token
string
required
Public token of the space where the task is created.
Get this from the Get All Spaces API — use the token field.

​
Headers

​
Authorization
string
required
API Key in format: Token <your-api-token>
​
Content-Type
string
required
Must be application/json

​
Request Body

​
pilot
string
required
Agent/pilot handle to assign the task to.
​
documents
array
required
Array of document/contact objects. Each document represents one contact to call.
​
context
string
Additional context/objective for the task (applies to all contacts).
​
schedule
object
Schedule configuration. Example: {"type": "now"}

​
Response Fields

​
status_code
integer
HTTP status code
​
message
string
Response message
​
data
object
Created task details

​
Common Error Codes

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

​
Code Examples

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.'
);

​
Best Practices

  1. Pilot Handle: Use the correct agent handle from the 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
  6. Security: Keep API tokens secure and rotate them regularly

Authorizations

​
Authorization
string
header
required

Format: Token

Headers

​
Org-Handle
string
required

Organization domain handle

Example:

"unpod.tv"

Path Parameters

​
space_token
string
required
Example:

"8KZAMRAHSXXXXXXMAYNASMJC"

Body

application/json
​
pilot
string
required

Agent/pilot handle to assign the task

Example:

"space-agent-f1o3qjm1y7q1avvuynv4vprb1"

​
documents
object[]
required

Array of contact/document objects

​
context
string

Additional context for the task

Example:

"Call the lead and discuss the project requirements."

​
schedule
object

Schedule configuration

Example:
{ "type": "now" }

Response

Task created successfully