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

namestringrequired

Request

POST/v1/projects

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)

POST/v1/projects

import scaleapi

# Initialize the ScaleClient with your API key
client = scaleapi.ScaleClient("YOUR_API_KEY_HERE")

# Define the project name you want to retrieve
project_name = "kitten_labeling"

# Retrieve the project details
project = client.get_project(project_name=project_name)

# Print the project details
print(project.as_dict())

Response

{
   "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.

Request

POST/v1/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)

POST/v1/projects

import scaleapi

# Initialize the ScaleClient with your API key
client = scaleapi.ScaleClient("YOUR_API_KEY_HERE")

# Retrieve the list of all projects
projects = client.get_projects()

# Iterate over the projects and print their details
for project in projects:
    print(project.as_dict())

Response

{
  "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

typestringrequired

The task type of all the tasks belonging to this project

namestringrequired

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.

rapidboolean

Whether the project being created is a Scale Rapid project. Enterprise and On-Demand customers should omit this value.

studioboolean

Whether the project being created is a Scale Studio project. Enterprise and On-Demand customers should omit this value.

paramsobject

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.

pipelinestring

Studio projects only. Specify the pipeline of the project. Must use either standard_task or consensus_task.

consensus_attemptsinteger

Studio consensus projects only. Specify the number of attempts

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"

# 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)

import scaleapi
from scaleapi.tasks import TaskType

# Initialize the ScaleClient with your API key
client = scaleapi.ScaleClient("YOUR_API_KEY_HERE")

# Define the project payload
project_payload = {
    "type": TaskType.ImageAnnotation,
    "name": "project_name",
    "rapid": False,  # Set to True if creating a Scale Rapid project
    "studio": True,  # Set to True if creating a Scale Studio project
    "params": {
        "instruction": "Instructions"
    },
    "pipeline": "pipeline_name"  # Specify the pipeline name for Studio projects
}

# Create the project
project = client.create_project(**project_payload)

# Print the created project's details
print(project.as_dict())

Response

{
"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

patchboolean

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.

instructionstring

instruction field to combine with any specified task-level instruction.

anyobject

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.

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)

import scaleapi

# Initialize the ScaleClient with your API key
client = scaleapi.ScaleClient("YOUR_API_KEY_HERE")

# Function to set project parameters
def set_project_params(client, project_name: str, params: dict):
    """
    Set parameters for a project.

    Args:
        client (ScaleClient): The ScaleClient instance.
        project_name (str): The name of the project to update.
        params (dict): A dictionary of parameters to set.
    """
    response = client.update_project(project_name, **params)
    return response

# Example usage
project_name = "example_project"
params = {
    "instruction": "Please label the objects in the image.",
    "priority": 10,
    "additional_param": "value"
}

response = set_project_params(client, project_name, params)
print(response)

Response

{
   "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"
}

Update Ontology (Project)

You can set ontologies on a project. Ontologies will be referenced by the tasks of a project. Projects keep a history of the ontologies they were set with.The ontology can be composed of a list of strings or OntologyChoice objects. Ontology choices and their subchoices must be unique throughout the ontology.

Path Params

namestringrequired

Body Params

ontologyarray of strings

A list of string or OntologyChoice objects

namestring

Name identifying the version of the ontology.

Request

POSTv1/projects/{Name}/setOntology

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/setOntology"

# Define the payload to update the project's ontology
payload = { 
    "name": "ontologyName",  # Name of the ontology to be set
    "ontology": [
        "ontology_string1",
        "ontology_string2",
        "ontology_string3"
    ]
}

# Set up the headers for the request
headers = {
    "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)

POSTv1/projects/{Name}/setOntology

import scaleapi

# Initialize the ScaleClient with your API key
client = scaleapi.ScaleClient("YOUR_API_KEY_HERE")

# Function to update ontology for a project
def update_project_ontology(client, project_name: str, ontology: list, ontology_name: str):
    """
    Update the ontology for a project.

    Args:
        client (ScaleClient): The ScaleClient instance.
        project_name (str): The name of the project to update.
        ontology (list): A list of ontology strings or OntologyChoice objects.
        ontology_name (str): The name identifying the version of the ontology.
    """
    endpoint = f"projects/{project_name}/setOntology"
    payload = {
        "name": ontology_name,
        "ontology": ontology
    }
    response = client.api.post_request(endpoint, body=payload)
    return response

# Example usage
project_name = "example_project"
ontology = [
    "ontology_string1",
    "ontology_string2",
    "ontology_string3"
]
ontology_name = "ontology_test"

response = update_project_ontology(client, project_name, ontology, ontology_name)
print(response)

Response

{
   "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"
   }