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

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

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

POSTv1/projects/{Name}/setOntology
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"
   }
Updated 5 days ago