> ## Documentation Index > Fetch the complete documentation index at: https://vida.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a new task > Creates communication, scheduled, or Computer Agent work. Computer Tasks run only on provisioned Computer Agents and preserve their complete work in a linked conversation. ## OpenAPI ````yaml post /api/v2/tasks openapi: 3.0.0 info: version: 2.0.0 title: Vida API description: Vida API Documentation servers: - url: https://api.vida.dev description: Vida Production variables: baseUrl: default: api.vida.dev description: Production API Root security: [] tags: - name: Agents - name: Apps description: Install Vida apps and use their enabled integration functions. - name: Integrations description: Configure Vader integrations. - name: Inbound Email description: Control which senders may create inbound email work for an Agent. - name: Features description: Inspect capabilities available within an account hierarchy. - name: Conversation Logs description: Query conversation activity and calculate account-level metrics. - name: Computer Agents description: Set up, configure, inspect, and manage Vida Computer Agents. - name: Computer Agent Sessions description: View and reset Computer Agent sessions. - name: Accounts - name: Agent Templates description: Create, manage, and apply reusable Agent configurations. paths: /api/v2/tasks: post: tags: - Tasks summary: Create a new task description: >- Creates communication, scheduled, or Computer Agent work. Computer Tasks run only on provisioned Computer Agents and preserve their complete work in a linked conversation. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TaskCreate' responses: '201': description: Task created successfully '400': description: Invalid Task, goal, or retry policy '401': description: Unauthorized '409': description: An active retryable Task already exists for this agent and contact '500': description: Internal Server Error security: - apiKeyAuth: [] components: schemas: TaskCreate: oneOf: - $ref: '#/components/schemas/TaskCallCreate' - $ref: '#/components/schemas/TaskTextCreate' - $ref: '#/components/schemas/TaskEmailCreate' - $ref: '#/components/schemas/TaskPingCreate' - $ref: '#/components/schemas/TaskComputerCreate' - $ref: '#/components/schemas/TaskRepeatingCreate' - $ref: '#/components/schemas/TaskCronOneOffCreate' discriminator: propertyName: type mapping: call: '#/components/schemas/TaskCallCreate' text: '#/components/schemas/TaskTextCreate' email: '#/components/schemas/TaskEmailCreate' ping: '#/components/schemas/TaskPingCreate' computer: '#/components/schemas/TaskComputerCreate' repeating: '#/components/schemas/TaskRepeatingCreate' cronOneOff: '#/components/schemas/TaskCronOneOffCreate' TaskCallCreate: type: object required: - type - target properties: type: type: string enum: - call target: type: string description: >- Phone number, email address, or supported Vida username for this Task type. example: '+15551234567' accountId: type: integer description: Agent account that performs the Task. example: 1234 title: type: string context: type: string description: Contact context supplied to the Agent. taskContext: type: string description: Instructions for the Agent performing this Task. example: Confirm whether the customer wants a renewal quote. scheduledFor: type: integer description: Unix timestamp for the first attempt or Computer Agent run. example: 1712350000 externalTaskId: type: string description: Reusable caller-defined correlation ID; not an idempotency key. contactListName: type: string goal: $ref: '#/components/schemas/TaskGoal' retryPolicy: $ref: '#/components/schemas/TaskRetryPolicy' meta: type: object description: >- Metadata retained for filtering and reporting; it is not added to the Agent prompt. additionalProperties: true properties: contact: $ref: '#/components/schemas/TaskContactFields' greeting: type: string description: >- Call greeting. Prefix with prompt: to generate it from an instruction. waitToGreet: type: boolean TaskTextCreate: type: object required: - type - target properties: type: type: string enum: - text target: type: string description: >- Phone number, email address, or supported Vida username for this Task type. example: '+15551234567' accountId: type: integer description: Agent account that performs the Task. example: 1234 title: type: string context: type: string description: Contact context supplied to the Agent. taskContext: type: string description: Instructions for the Agent performing this Task. example: Confirm whether the customer wants a renewal quote. scheduledFor: type: integer description: Unix timestamp for the first attempt or Computer Agent run. example: 1712350000 externalTaskId: type: string description: Reusable caller-defined correlation ID; not an idempotency key. contactListName: type: string goal: $ref: '#/components/schemas/TaskGoal' retryPolicy: $ref: '#/components/schemas/TaskRetryPolicy' meta: type: object description: >- Metadata retained for filtering and reporting; it is not added to the Agent prompt. additionalProperties: true properties: contact: $ref: '#/components/schemas/TaskContactFields' message: type: string description: Initial text message. TaskEmailCreate: type: object required: - type - target properties: type: type: string enum: - email target: type: string description: >- Phone number, email address, or supported Vida username for this Task type. example: '+15551234567' accountId: type: integer description: Agent account that performs the Task. example: 1234 title: type: string context: type: string description: Contact context supplied to the Agent. taskContext: type: string description: Instructions for the Agent performing this Task. example: Confirm whether the customer wants a renewal quote. scheduledFor: type: integer description: Unix timestamp for the first attempt or Computer Agent run. example: 1712350000 externalTaskId: type: string description: Reusable caller-defined correlation ID; not an idempotency key. contactListName: type: string goal: $ref: '#/components/schemas/TaskGoal' retryPolicy: $ref: '#/components/schemas/TaskRetryPolicy' meta: type: object description: >- Metadata retained for filtering and reporting; it is not added to the Agent prompt. additionalProperties: true properties: contact: $ref: '#/components/schemas/TaskContactFields' message: type: string description: Initial email body. TaskPingCreate: type: object required: - type properties: type: type: string enum: - ping target: type: string description: >- Phone number, email address, or supported Vida username for this Task type. example: '+15551234567' accountId: type: integer description: Agent account that performs the Task. example: 1234 title: type: string context: type: string description: Contact context supplied to the Agent. taskContext: type: string description: Instructions for the Agent performing this Task. example: Confirm whether the customer wants a renewal quote. scheduledFor: type: integer description: Unix timestamp for the first attempt or Computer Agent run. example: 1712350000 externalTaskId: type: string description: Reusable caller-defined correlation ID; not an idempotency key. contactListName: type: string goal: $ref: '#/components/schemas/TaskGoal' retryPolicy: $ref: '#/components/schemas/TaskRetryPolicy' meta: type: object description: >- Metadata retained for filtering and reporting; it is not added to the Agent prompt. TaskComputerCreate: type: object additionalProperties: false required: - type - accountId - taskContext properties: type: type: string enum: - computer accountId: type: integer description: Agent account that performs the Task. example: 1234 title: type: string taskContext: type: string description: Instructions for the Agent performing this Task. example: Confirm whether the customer wants a renewal quote. scheduledFor: type: integer description: Unix timestamp for the first attempt or Computer Agent run. example: 1712350000 externalTaskId: type: string description: Reusable caller-defined correlation ID; not an idempotency key. meta: type: object description: Caller metadata. System-managed provider fields are reserved. TaskRepeatingCreate: type: object additionalProperties: false required: - type - accountId - title - taskContext - cronSchedule properties: type: type: string enum: - repeating accountId: type: integer description: Agent account that performs the Task. example: 1234 title: type: string taskContext: type: string description: Instructions for the Agent performing this Task. example: Confirm whether the customer wants a renewal quote. state: type: string enum: - active - paused default: active cronSchedule: $ref: '#/components/schemas/TaskCronSchedule' TaskCronOneOffCreate: type: object additionalProperties: false required: - type - accountId - title - taskContext - cronSchedule properties: type: type: string enum: - cronOneOff accountId: type: integer description: Agent account that performs the Task. example: 1234 title: type: string taskContext: type: string description: Instructions for the Agent performing this Task. example: Confirm whether the customer wants a renewal quote. state: type: string enum: - active - paused default: active cronSchedule: $ref: '#/components/schemas/TaskCronSchedule' TaskGoal: type: object nullable: true description: >- Task-specific outcome definition. Omit or pass null to inherit the organization default. required: - completionCriteria properties: completionCriteria: type: string description: Criteria evaluated after a connected conversation. description: type: string description: Optional goal label. TaskRetryPolicy: type: object nullable: true description: >- Task-specific cadence. Omit or pass null to inherit the organization default. Use delaysSeconds or steps, never both. required: - retryOn properties: delaysSeconds: type: array minItems: 1 maxItems: 10 description: Delays after each attempt, each from 60 seconds through 30 days. items: type: integer minimum: 60 maximum: 2592000 steps: type: array minItems: 1 maxItems: 10 description: >- Strictly increasing offsets from the first attempt for channel-specific retries. items: type: object required: - offsetSeconds - channel properties: offsetSeconds: type: integer minimum: 60 maximum: 7776000 channel: type: string enum: - call - text - email target: type: string description: Required when changing between phone and email channels. responseTimeoutSeconds: type: integer minimum: 60 maximum: 604800 content: type: object description: Channel-specific content override, up to 32 KB. retryOn: type: array minItems: 1 items: type: string enum: - busy - delivery_failed - goal_incomplete - no_answer - no_response - no_speech - rejected - transient_failure - voicemail responseTimeoutSeconds: type: integer minimum: 60 maximum: 604800 TaskContactFields: type: object additionalProperties: false description: >- Optional Contact fields for call, text and email Task creation, including outboundCall, outboundSms and outboundEmail. Fills missing fields on the target Contact in the Task organization before scheduling. Nested objects fill missing leaves; existing nonblank values, false, zero and nonempty arrays are preserved. Strings are trimmed; null, blank strings and empty objects/arrays are ignored. New Contacts use the supplied name instead of a global-profile default. Existing target phone/email defaults remain canonical. Does not change the Task target, global user profile or outbound caller ID. Task updates do not apply Contact changes; use the Contact API to replace or clear existing values. Identity and ownership fields are not accepted. See [Contact fields](https://vida.io/docs/api-reference/platform-guides/contacts-and-objectives#contact-fields) for the full field reference. properties: name: type: string nullable: true example: Example Person title: type: string nullable: true email: type: string nullable: true example: lead@example.com phone: type: string nullable: true example: '+15551234567' cnam: type: string nullable: true description: >- Organization Contact display data only; does not change outbound caller ID. mobile: type: string nullable: true birthday: type: string nullable: true gender: type: string nullable: true image: type: string nullable: true address: type: object nullable: true additionalProperties: false properties: street: type: string nullable: true city: type: string nullable: true state: type: string nullable: true zip: type: string nullable: true example: '07101' country: type: string nullable: true company: type: object nullable: true additionalProperties: false properties: name: type: string nullable: true industry: type: string nullable: true position: type: string nullable: true website: type: string nullable: true address: type: string nullable: true preferredContactMethod: type: string nullable: true marketingOptIn: type: boolean nullable: true contactSource: type: string nullable: true socialMedia: type: object nullable: true additionalProperties: false properties: linkedin: type: string nullable: true twitter: type: string nullable: true facebook: type: string nullable: true instagram: type: string nullable: true leadSource: type: string nullable: true status: type: string nullable: true tags: type: array nullable: true items: type: string notes: type: string nullable: true agentContext: type: string nullable: true customFields: type: object nullable: true additionalProperties: true maxProperties: 20 description: >- Custom JSON data, at most 20 top-level keys and 8192 UTF-8 JSON bytes, including existing values after merge. example: vendorLeadCode: lead-123 source: website lastTask: type: object nullable: true additionalProperties: false properties: taskId: oneOf: - type: string - type: number nullable: true listId: oneOf: - type: string - type: number nullable: true timestamp: type: number nullable: true success: type: boolean nullable: true lists: type: array nullable: true items: type: object required: - label properties: label: type: string timestamp: type: number appointments: type: array nullable: true items: type: object additionalProperties: true TaskCronSchedule: oneOf: - type: object additionalProperties: false required: - kind - at properties: kind: type: string enum: - at at: type: string format: date-time - type: object additionalProperties: false required: - kind - everyMs properties: kind: type: string enum: - every everyMs: type: integer minimum: 60000 - type: object additionalProperties: false required: - kind - expr properties: kind: type: string enum: - cron expr: type: string example: 0 * * * * tz: type: string example: America/Chicago securitySchemes: apiKeyAuth: type: apiKey in: query name: token description: Vida API Token ````