Skip to main content
POST
/
api
/
v1
/
tasks
Create Task
curl --request POST \
  --url https://api.example.com/api/v1/tasks

​
Create Task

Create a new task and start background AI agent execution. The endpoint returns immediately with the task ID. Connect to the Stream endpoint to receive real-time updates.

​
Request

POST /api/v1/tasks
Authorization: Bearer {api_key_or_jwt}
Content-Type: multipart/form-data
You can authenticate with either an API key (sigmic_...) or a JWT token (eyJ...) from Widget Authentication.

​
Form Fields

FieldTypeRequiredDefaultDescription
messagestringYes-The task instruction or prompt
systemPromptstringNonullCustom system prompt to prepend
showInHistorybooleanNotrueWhether to show this task in conversation history
autoExecutebooleanNotrueAutomatically approve tool executions
filesfile[]No-Files to upload (max 20 files, 50MB each)
envobjectNonullNon-sensitive environment variables (stored with task)
secretsobjectNonullSensitive environment variables (never stored, never logged)

​
Environment Variables

Both env and secrets accept key-value string maps. They are injected into the sandbox as process.env variables and as MCP server context for {{mcp.KEY}} template resolution.
  • env — Non-sensitive config (tenant IDs, feature flags). Stored with the task and returned in GET responses for debugging.
  • secrets — Sensitive credentials (API tokens, database URLs). Never stored, never logged, never returned in any response.
  • Keys must be valid env var names: letters, digits, and underscores, starting with a letter or underscore.
  • If the same key appears in both, secrets takes precedence.
When using env or secrets, send the request as application/json instead of multipart/form-data. File uploads require multipart/form-data and cannot be combined with env/secrets in the same request.

​
File Upload Notes

  • ZIP files are automatically extracted into the workspace
  • Files are uploaded to the workspace uploads/ directory
  • File paths are included in the context sent to the agent
  • Maximum 20 files per request
  • Maximum 50MB per file

​
Response

Returns JSON with the task ID. Execution starts in the background. 
{
  "success": true,
  "data": {
    "id": "c37c1d78-4d23-4e53-949a-ddd775f25e01",
    "status": "pending"
  }
}
FieldTypeDescription
idstringUnique task identifier
statusstringInitial status (pending)
After receiving the task ID, connect to GET /api/v1/tasks/:id/stream to receive real-time execution events including history replay and live streaming.

​
Examples

​
Basic Task

# 1. Create the task
RESPONSE=$(curl -s -X POST https://api.sigmic.ai/api/v1/tasks \
  -H "Authorization: Bearer sigmic_your_key_here" \
  -F "message=What is the capital of France?")

echo $RESPONSE
# {"success":true,"data":{"id":"c37c1d78-...","status":"pending"}}

# 2. Stream the execution
TASK_ID=$(echo $RESPONSE | jq -r '.data.id')
curl -N https://api.sigmic.ai/api/v1/tasks/$TASK_ID/stream \
  -H "Authorization: Bearer sigmic_your_key_here"

​
With File Upload

RESPONSE=$(curl -s -X POST https://api.sigmic.ai/api/v1/tasks \
  -H "Authorization: Bearer sigmic_your_key_here" \
  -F "message=Analyze this CSV file and summarize the data" \
  -F "files=@data.csv")

TASK_ID=$(echo $RESPONSE | jq -r '.data.id')
curl -N https://api.sigmic.ai/api/v1/tasks/$TASK_ID/stream \
  -H "Authorization: Bearer sigmic_your_key_here"

​
With Manual Tool Approval

Set autoExecute=false to review tool calls before they execute: 
RESPONSE=$(curl -s -X POST https://api.sigmic.ai/api/v1/tasks \
  -H "Authorization: Bearer sigmic_your_key_here" \
  -F "message=List all files in the current directory" \
  -F "autoExecute=false")

TASK_ID=$(echo $RESPONSE | jq -r '.data.id')
When a tool call requires approval, the stream will emit a tool_call event with status: awaiting_approval. You can also poll GET /api/v1/tasks/:id and check the pendingApprovals array. Use the Approve Tool Call endpoint to approve or reject it.

​
With Environment Variables

Inject credentials and configuration into the sandbox: 
curl -s -X POST https://api.sigmic.ai/api/v1/tasks \
  -H "Authorization: Bearer sigmic_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Query the database and generate a report",
    "env": { "TENANT_ID": "acme-corp", "REPORT_FORMAT": "csv" },
    "secrets": { "DATABASE_URL": "postgres://user:pass@host/db" }
  }'
The agent’s sandbox will have TENANT_ID, REPORT_FORMAT, and DATABASE_URL available as process.env variables. MCP servers configured with {{mcp.DATABASE_URL}} in their headers will have the value resolved automatically.

​
With Custom System Prompt

curl -s -X POST https://api.sigmic.ai/api/v1/tasks \
  -H "Authorization: Bearer sigmic_your_key_here" \
  -F "message=Write a greeting" \
  -F "systemPrompt=You are a helpful assistant that always responds in Spanish."

​
Errors

CodeDescription
AUTH_REQUIREDNo authentication provided
INVALID_API_KEYInvalid or expired API key
VALIDATION_ERRORMissing or invalid message field, or invalid env var name
EXECUTION_ERRORTask execution failed