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
import requests
url = "https://api.scale.com/v1/projects/kitten_labeling"
headers = {"accept": "application/json"}
response = requests.get(url, headers=headers)
print(response.text)
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"
}
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
import requests
url = "https://api.scale.com/v1/projects"
headers = {
"accept": "application/json",
}
response = requests.get(url, headers=headers)
print(response.text)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
url = "https://api.scale.com/v1/projects"
payload = {
"type": "imageannotation",
"name": "project_name",
"rapid": False,
"studio": True,
"params": { "instruction": "Instructions" },
"pipeline": "pipelinen_name"
}
headers = {
"accept": "application/json",
"content-type": "application/json",
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)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
url = "https://api.scale.com/v1/projects/kitten_labeling/setParams"
payload = {"patch": "false"}
headers = {
"accept": "application/json",
"content-type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)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
import requests
url = "https://api.scale.com/v1/projects/project_name/setOntology"
payload = {
"name": "ontology_test",
"ontology": [
"ontology_string1",
"ontology_string2",
"ontology_string3",
]
}
headers = {
"content-type": "application/json",
}
response = requests.post(url, headers=headers)
print(response.text)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"
}