Skip to main content
POST
/
v2
/
task
/
chat
API_KEY='live_...'
curl --request POST \
    --url "https://api.scale.com/v2/task/chat" \
    --header "Authorization: Bearer $API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "project_name": "My Chat Project",
      "template_variables": {
        "prompt": "Explain quantum computing",
        "context": "For a general audience"
      },
      "metadata": {
        "priority": "high",
        "source": "api"
      }
    }'
{
  "task_id": "task_123",
  "project": "project_123",
  "batch": "batch_123",
  "status": "pending",
  "created_at": "2025-01-01T08:31:03.169Z",
  "threads": []
}
Every request sent to Scale’s API requires authentication. In short, your API Key is the Bearer token. See the Authentication section for more details.

​
Required parameters

You are expected to provide one of the following:
  • Project ID (project_id)
  • Project Name (project_name)

​
Template Variables

Template variables are key-value pairs that populate your project’s task template. The available variables depend on your specific project configuration.Common template variables:
  • prompt - The main instruction or question for the task
  • context - Additional context or background information
  • examples - Sample inputs or outputs to guide the task
  • constraints - Specific requirements or limitations

Authorizations

​
Authorization
string
header
required

Your API Key is the Bearer token. See the Authentication section to learn how to access your key.

Body

application/json
​
project_id
string

A unique identifier for the project.

Example:

"project_abc123"

​
project_name
string

The name of the project.

Example:

"My Scale Project"

​
batch_id
string

A unique identifier for the batch.

Example:

"batch_abc123"

​
batch_name
string

The name of the batch.

Example:

"My Scale Batch"

​
template_variables
object

Template variables for task creation.

​
metadata
object

Custom metadata for the entity.

​
callback_url
string

Callback URL or email for the entity upon completion.

Example:

"https://example.com/callback"

Response

Chat task created successfully.

​
task_id
string
required

Unique identifier for the task.

Example:

"task_abc123"

​
project
required

Project ID or Project associated with the task.

Example:

"project_abc123"

​
status
enum<string>
required

Current status of the task.

Available options:
pending,
completed,
canceled,
error
​
created_at
string<date-time>
required

UTC timestamp when the task was created.

​
batch

Batch ID or Batch associated with the task.

Example:

"batch_abc123"

​
completed_at
string<date-time>

UTC timestamp when the task was completed.

​
metadata
object

Custom metadata for the entity.

​
threads
object[]

Threads associated with the task. Tasks that do not have a status of completed will have an empty threads array.

​
errors
object[]

Errors associated with the task. Available when the task status is error

​
sensitive_content_reports
object[]

Reports of sensitive content within the task. Available when the task status is completed. threads will not exist when the task is reported.