> ## Documentation Index
> Fetch the complete documentation index at: https://api-reference.scale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Projects

> Project Retrieval List All Projects Create Project Update Project Parameters

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

<ParamField path="Body Params" type="object">
  <ParamField path="name" type="string" required>
    ***
  </ParamField>
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  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)

  ```

  ```python Python SDK theme={null}
  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())

  ```
</CodeGroup>

```json theme={null}
{
   "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.

<CodeGroup>
  ```python Python theme={null}
  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)

  ```

  ```python Python SDK theme={null}
  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())

  ```
</CodeGroup>

```json theme={null}
{
  "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.<br />

<ParamField path="Body Params" type="object">
  <ParamField path="type" type="string" required>
    The task type of all the tasks belonging to this project

    ***
  </ParamField>

  <ParamField path="name" type="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.

    ***
  </ParamField>

  <ParamField path="rapid" type="boolean">
    Whether the project being created is a Scale Rapid project. Enterprise and On-Demand customers should omit this value.

    ***
  </ParamField>

  <ParamField path="studio" type="boolean">
    Whether the project being created is a Scale Studio project. Enterprise and On-Demand customers should omit this value.

    ***
  </ParamField>

  <ParamField path="params" type="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.

    ***
  </ParamField>

  <ParamField path="pipeline" type="string">
    Studio projects only. Specify the pipeline of the project. Must use either standard\_task or consensus\_task.

    ***
  </ParamField>

  <ParamField path="consensus_attempts" type="integer">
    Studio consensus projects only. Specify the number of attempts

    ***
  </ParamField>
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  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)

  ```

  ```python Python SDK theme={null}
  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())

  ```
</CodeGroup>

```json theme={null}
{
"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](/docs/api-reference/data-engine-reference#using-project-level-parameters)**[ ](/docs/api-reference/data-engine-reference#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](/docs/api-reference/projects)**.

<ParamField path="Body Params" type="object">
  <ParamField path="patch" type="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.

    ***
  </ParamField>

  <ParamField path="instruction" type="string">
    instruction field to combine with any specified task-level instruction.

    ***
  </ParamField>

  <ParamField path="any" type="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.

    ***
  </ParamField>
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  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)

  ```

  ```python Python SDK theme={null}
  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)

  ```
</CodeGroup>

```json theme={null}
{
   "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"
}
```