Get Started
Project Archetypes
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": []
}Create a Chat Task
Create a new Task for GenAI projects. Uses structured task templates, not free-form instructions.
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": []
}Authentication
Authentication
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 taskcontext- Additional context or background informationexamples- Sample inputs or outputs to guide the taskconstraints- Specific requirements or limitations
Authorizations
Your API Key is the Bearer token. See the Authentication section to learn how to access your key.
Body
A unique identifier for the project.
"project_abc123"
The name of the project.
"My Scale Project"
A unique identifier for the batch.
"batch_abc123"
The name of the batch.
"My Scale Batch"
Template variables for task creation.
Custom metadata for the entity.
Callback URL or email for the entity upon completion.
"https://example.com/callback"
Response
Chat task created successfully.
Unique identifier for the task.
"task_abc123"
Current status of the task.
pending, completed, canceled, error UTC timestamp when the task was created.
UTC timestamp when the task was completed.
Custom metadata for the entity.
Threads associated with the task. Tasks that do not have a status of completed will have an empty threads array.
Show child attributes
Show child attributes
Unique identifier for the thread.
"thread_abc123"
Turns within the thread.
Show child attributes
Show child attributes
A unique identifier for the turn.
"turn_abc123"
A list of messages associated with this turn.
Show child attributes
Show child attributes
The role of the sender in the conversation (e.g., user, assistant).
system, user, assistant, function The content of the message, including text and any attachments.
Show child attributes
Show child attributes
The textual content of the message.
The reference texts associated with the message.
Any files or attachments included with the message.
- File
- Detailed Image File
- Detailed Audio File
Show child attributes
Show child attributes
The base64-encoded content of the file.
The MIME type of the file, indicating its format.
"text/plain"
A URL pointing to the location of the file in Scale's storage.
A URL pointing to the source location of the file.
The name of the file.
Chunks specific to this message.
Show child attributes
Show child attributes
The type of chunked data.
Annotations for a chunk of the message.
Represents a generic annotation.
- Integer
- Boolean
- Text
- Category
- Category-Multiple
- File
- Workspace Container
- Ranked Choices
- Ranked Groups
Show child attributes
Show child attributes
Unique identifier for the annotation.
"an_abc123efg456"
Key for the annotation.
"formatting"
The type of the value and the possible_values, if they exist.
Title of the annotation.
"Response Formatting"
Further details about the question.
"Does the response contain issues with formatting?"
String representation of the possible options.
A string representation of the annotation.
["Major Issues", "Minor Issues", "No Issues"]Integer type annotation value.
3
The possible values for this annotation.
Integer type annotation value.
A plain text field.
The ID of the source system or user that sent the message.
"source_abc123"
Annotations specific to this message.
Represents a generic annotation.
- Integer
- Boolean
- Text
- Category
- Category-Multiple
- File
- Workspace Container
- Ranked Choices
- Ranked Groups
Show child attributes
Show child attributes
Unique identifier for the annotation.
"an_abc123efg456"
Key for the annotation.
"formatting"
The type of the value and the possible_values, if they exist.
Title of the annotation.
"Response Formatting"
Further details about the question.
"Does the response contain issues with formatting?"
String representation of the possible options.
A string representation of the annotation.
["Major Issues", "Minor Issues", "No Issues"]Integer type annotation value.
3
The possible values for this annotation.
Integer type annotation value.
Show child attributes
Show child attributes
The name of the model that generated the message.
"my-model-123"
The temperature of the model that generated the message.
0.9
The maximum number of tokens the model can generate.
1000
The top-p value of the model that generated the message.
0.9
The top-k value of the model that generated the message.
4
Annotations applied to the entire turn.
Represents a generic annotation.
- Integer
- Boolean
- Text
- Category
- Category-Multiple
- File
- Workspace Container
- Ranked Choices
- Ranked Groups
Show child attributes
Show child attributes
Unique identifier for the annotation.
"an_abc123efg456"
Key for the annotation.
"formatting"
The type of the value and the possible_values, if they exist.
Title of the annotation.
"Response Formatting"
Further details about the question.
"Does the response contain issues with formatting?"
String representation of the possible options.
A string representation of the annotation.
["Major Issues", "Minor Issues", "No Issues"]Integer type annotation value.
3
The possible values for this annotation.
Integer type annotation value.
Annotations for the entire thread.
Represents a generic annotation.
- Integer
- Boolean
- Text
- Category
- Category-Multiple
- File
- Workspace Container
- Ranked Choices
- Ranked Groups
Show child attributes
Show child attributes
Unique identifier for the annotation.
"an_abc123efg456"
Key for the annotation.
"formatting"
The type of the value and the possible_values, if they exist.
Title of the annotation.
"Response Formatting"
Further details about the question.
"Does the response contain issues with formatting?"
String representation of the possible options.
A string representation of the annotation.
["Major Issues", "Minor Issues", "No Issues"]Integer type annotation value.
3
The possible values for this annotation.
Integer type annotation value.
Errors associated with the task. Available when the task status is error
Show child attributes
Show child attributes
Type of the error
UNSUPPORTED_LANGUAGE, LANGUAGE_MISMATCH, PROMPT_LENGTH_EXCEEDED, INVALID_CATEGORY, PROMPT_INFEASIBLE "UNSUPPORTED_LANGUAGE"
Details of the error message. e.g. Locale is not supported
"The specified language or locale is not supported"
Reports of sensitive content within the task. Available when the task status is completed. threads will not exist when the task is reported.