Skip to main content

​
Project Retrieval

The project retrieval endpoint allows you to get details about a specific project using its unique ID. It provides access to project-related data, such as name, status, task count, and metadata. You can use this endpoint to integrate with the Scale API for programmatic project management and monitoring. Don’t forget to authenticate your requests with a valid API key for successful access.
​
Body Params
object
​
name
string
required
import requests

# Replace with your actual API key
API_KEY = 'your_api_key_here'

# Define the URL for the API endpoint
url = "https://api.scale.com/v1/projects/kitten_labeling"

# Set up the headers for the request
headers = {
    "accept": "application/json"  # Specify that we want the response in JSON format
}

# Adding authentication to the GET request
# The auth parameter requires a tuple with the API key and an empty string
response = requests.get(url, headers=headers, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)


{
   "type": "imageannotation",
   "name": "kitten_labeling",
   "param_history": [
       {
       "instruction": "Instructions",
       "version": 0,
       "created_at": "2021-04-25T07:38:32.368Z"
       }
   ],
   "created_at": "2021-04-25T07:38:32.368Z"
}

​
List All Projects

List information for all projects. Note: No parameters required. Optionally, set a boolean value for archived to only list information for all (un)archived projects. 
import requests
from requests.auth import HTTPBasicAuth

# URL endpoint for the API call
url = "https://api.scale.com/v1/projects"

# Headers to specify the type of response we accept (JSON in this case)
headers = {"accept": "application/json"}

# Authentication using HTTP Basic Auth; provide your API key as the username
# No password is required, so the password field is empty
auth = HTTPBasicAuth('{{ApiKey}}', '')  

# Performing a GET request to the API with headers and authentication
response = requests.get(url, headers=headers, auth=auth)

# Printing the text content of the response from the API
print(response.text)


{
  "type": "imageannotation",
  "name": "project_name",
  "param_history": [
    {
      "instruction": "Instructions",
      "version": 0,
      "created_at": "2021-04-25T07:38:32.368Z"
    }
  ],
  "created_at": "2021-04-25T07:38:32.368Z"
}

​
Create Project

The project creation endpoint enables you to programmatically create new projects on the Scale API platform. It allows automation of project creation, streamlining data annotation workflows, and efficient management of multiple projects. You need valid authentication credentials (API key) and relevant project information to use this endpoint successfully.
​
Body Params
object
​
type
string
required
The task type of all the tasks belonging to this project
​
name
string
required
Name identifying this project. Must be unique among all your projects. When creating tasks for this project, you should add a project: <name> parameter to the task creation request to associate the task with this project.
​
rapid
boolean
Whether the project being created is a Scale Rapid project. Enterprise and On-Demand customers should omit this value.
​
studio
boolean
Whether the project being created is a Scale Studio project. Enterprise and On-Demand customers should omit this value.
​
params
object
Default parameters for tasks created under this project. Any parameters specified here will be set if omitted in a task request; they will be overridden by any values sent in the task request. params.instruction behaves slightly differently; values here will instead be appended after the task-level instruction.
​
pipeline
string
Studio projects only. Specify the pipeline of the project. Must use either standard_task or consensus_task.
​
consensus_attempts
integer
Studio consensus projects only. Specify the number of attempts
import requests

# Replace with your actual API key
API_KEY = 'your_api_key_here'

# Define the URL for the API endpoint
url = "https://api.scale.com/v1/projects"

# Define the payload for creating a new project
payload = {
    "type": "imageannotation",  # Type of the project
    "name": "kitten_labeling",  # Name of the project
    "rapid": False,             # Indicates if the project is a rapid project
    "studio": False,            # Indicates if the project uses Scale AI's Studio interface
    "params": { 
        "instruction": "Please label the kittens"  # Instructions for the annotation task
    }
}

# Set up the headers for the request
headers = {
    "accept": "application/json",      # Specify that we want the response in JSON format
    "content-type": "application/json" # Specify the content type of the request
}

# Adding authentication to the POST request
# The auth parameter requires a tuple with the API key and an empty string
response = requests.post(url, json=payload, headers=headers, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)


{
"type": "imageannotation",
"pipelineName": "pipeline_name",
"numReviews": 0,
"numConsensus": 0,
"created_at": "2023-08-04T15:11:57.508Z",
"created_by": "user_id",
"created_with": "api",
"param_history": [],
"projectType": "project_type",
"name": "project_name",
"pinned": false,
"archived": false,
"nucleusDatasetId": "nucleus_id",
"customGradersUsedOrDismissed": false,
"edgeCaseAlertsEnabled": false,
"turnOnLongHints": true,
"isAudioTranscription": false,
"useOldOnboarding": false,
"containsAdultContent": false,
"useRapidSmartTraining": false,
"useTextCollectionTemplate": false,
"datasetLinks": [
{
  "datasetId": "dataset_id",
  "datasetName": "dataset_name"
}
],
"taxonomy": null,
"isSampleProject": false,
"modelEvalProject": false
}

​
Update Project Parameters

You can set parameters on a project. Project-level-parameters will be set on future tasks created under this project if they are not set in the task request. Any parameters specified in the task request will override any project parameter. Projects keep a history of the parameters that they were set with. Tasks created under a project inherit the latest params of the project (the last entry in param_history), one can also specify project_version when creating a task to inherit from an older set of params (or use -1 to skip parameter inheritance altogether.) Tasks have a **project_param_version** field pointing to the project version in place at the time a task was created. If you haven’t already, check out our guide to using Project-level parameters to learn more about how this workflow comes togeher. Just want to see some examples? We’ve added those as well.
​
Body Params
object
​
patch
boolean
When generating the newest set of project parameters, whether or not to combine the most recent project parameters with the parameters specified in this request. Defaults to false. For example, if the current params contains { instruction: ‘label the cats in the image’ } and the latest call to this API contains the task parameter { objects_to_annotate: [‘cat’] }, whether or not patch is additionally set will determine if the new project parameters also contain the instruction “label the cats in the image”. Note that any fields set in the API request completely override any fields from the previous version; object or array values will not be merged.
​
instruction
string
instruction field to combine with any specified task-level instruction.
​
any
object
Default parameters for tasks created under this project. Any parameters specified here will be set if omitted in a task request; they will be overridden by any values sent in the task request.
import requests

# Replace with your actual API key
API_KEY = 'your_api_key_here'

# Define the URL for the API endpoint
url = "https://api.scale.com/v1/projects/kitten_labeling/setParams"

# Define the payload to update project parameters
payload = { 
    "patch": "false"  # Parameter to be updated
}

# Set up the headers for the request
headers = {
    "accept": "application/json",      # Specify that we want the response in JSON format
    "content-type": "application/json" # Specify the content type of the request
}

# Adding authentication to the POST request
# The auth parameter requires a tuple with the API key and an empty string
response = requests.post(url, json=payload, headers=headers, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)


{
   "type": "imageannotation",
   "name": "kitten_labeling",
   "param_history": [
       {
       "instruction": "please label the kittens in the image",
       "version": 0,
       "created_at": "2021-04-25T07:38:32.368Z"
       }
    ],
   "created_at": "2021-04-25T07:38:32.368Z"
}