### Install and Authenticate Valispace API Client

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Install the library using pip. Initialize the API client with your Valispace URL and credentials (username/password or session token). The `keep_credentials` option maintains credentials in memory for automatic re-authentication.

```python
# Install
# pip install valispace

import valispace

# Interactive login (prompts for URL, username, password)
vs = valispace.API()

# Inline credentials
vs = valispace.API(
    url='https://demo.valispace.com',
    username='alice',
    password='s3cr3t'
)

# Token-based authentication (skips OAuth flow)
vs = valispace.API(
    url='https://demo.valispace.com',
    session_token='Bearer eyJ0eXAiOiJKV1QiLCJhbGci...'
)

# Keep credentials in memory for automatic re-auth on token expiry
vs = valispace.API(
    url='https://demo.valispace.com',
    username='alice',
    password='s3cr3t',
    keep_credentials=True
)
```

--------------------------------

### Install Valispace Python API

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Install the Valispace python API using pip. This is the first step to using the API.

```bash
pip install valispace
```

--------------------------------

### Get a Specific Project by Name

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a Project object by its name.

```python
valispace.get_project_by_name(name='Fan')
```

--------------------------------

### Raw REST Access with GET, POST, PATCH, DELETE

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Low-level methods for accessing any Valispace REST endpoint. URLs are relative to the deployment's /rest/ base path. Use GET for retrieval, POST for creation, PATCH for updates, and DELETE for removal.

```python
# GET any endpoint
projects = vs.get('project/')
vali_42  = vs.get('valis/42/')

# POST to a custom endpoint
new_req = vs.post('requirements/', {
    'specification': 3,
    'identifier': 'REQ-001',
    'title': 'Mass budget',
    'text': 'Total dry mass shall not exceed 5500 kg.'
})

# PATCH a Vali formula directly
vs.request('PATCH', 'valis/42/', data={'formula': '5300 + 200'})

# DELETE
vs.request('DELETE', 'valis/99/')
```

--------------------------------

### Get a List of Valis

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a dictionary containing all Valis from your Valispace deployment.

```python
valis = valispace.get_vali_list()
```

--------------------------------

### Shortcut GET Request

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

A shortcut for making GET requests using the `request` method.

```APIDOC
## Shortcut GET Request

### Description
Shortcut for making a GET request.

### Method
`get`

### Parameters
- **url** (string) - Required - The API endpoint URL.
- **data** (object) - Optional - Query parameters for the GET request.
```

--------------------------------

### Get Project by Name

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a specific Project object by its name.

```APIDOC
## Get Project by Name

### Description
Retrieve a specific Project object by its name.

### Method
`valispace.get_project_by_name(name)`

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the Project.

### Request Example
```python
project = valispace.get_project_by_name(name='Fan')
```
```

--------------------------------

### Get Project List

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a list of Projects, with optional filtering by workspace.

```APIDOC
## Get Project List

### Description
Retrieve a list of Projects, with optional filtering by workspace.

### Method
`valispace.get_project_list()`

### Parameters
#### Query Parameters
- **workspace_id** (integer) - Optional - Filter by workspace ID.
- **workspace_name** (string) - Optional - Filter by workspace name.

### Request Example
```python
# Get all projects
projects = valispace.get_project_list()

# Filter by workspace name
projects = valispace.get_project_list(workspace_name='Default Workspace')
```
```

--------------------------------

### Get Project Folders and Groups

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Retrieve the folder and group hierarchy for organizing requirements within a project.

```python
folders = vs.get_folders(project_id=1)
groups  = vs.get_groups(project_id=1)
```

--------------------------------

### Get Component List

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a list of Components, with optional filtering by workspace, project, parent, or tag.

```APIDOC
## Get Component List

### Description
Retrieve a list of Components, with optional filtering by workspace, project, parent, or tag.

### Method
`valispace.get_component_list()`

### Parameters
#### Query Parameters
- **workspace_id** (integer) - Optional - Filter by workspace ID.
- **workspace_name** (string) - Optional - Filter by workspace name.
- **project_id** (integer) - Optional - Filter by project ID.
- **project_name** (string) - Optional - Filter by project name.
- **parent_id** (integer) - Optional - Filter by parent ID.
- **parent_name** (string) - Optional - Filter by parent name.
- **tag_id** (integer) - Optional - Filter by tag ID.
- **tag_name** (string) - Optional - Filter by tag name.

### Request Example
```python
# Get all components
components = valispace.get_component_list()

# Filter by project name
components = valispace.get_component_list(project_name='Fan')
```
```

--------------------------------

### Get All Vali Names

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a list of all Vali IDs and their corresponding names.

```python
all_vali_names = valispace.get_vali_names()
```

--------------------------------

### Get Project by ID

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a specific Project object with all its properties using its ID.

```APIDOC
## Get Project by ID

### Description
Retrieve a specific Project object with all its properties using its ID.

### Method
`valispace.get_project(id)`

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the Project to retrieve.

### Request Example
```python
project = valispace.get_project(id=1)
```
```

--------------------------------

### Get a Specific Project by ID

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a Project object with all its properties using its unique ID.

```python
valispace.get_project(id=1)
```

--------------------------------

### Get Vali Names

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a dictionary of all Vali IDs and their corresponding names.

```APIDOC
## Get Vali Names

### Description
Retrieve a dictionary of all Vali IDs and their corresponding names.

### Method
`valispace.get_vali_names()`

### Parameters
None

### Request Example
```python
all_vali_names = valispace.get_vali_names()
```
```

--------------------------------

### Get Component by Name

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a specific Component object by its unique name within a project.

```APIDOC
## Get Component by Name

### Description
Retrieve a specific Component object by its unique name within a project.

### Method
`valispace.get_component_by_name(unique_name, project_name)`

### Parameters
#### Query Parameters
- **unique_name** (string) - Required - The unique name of the Component.
- **project_name** (string) - Required - The name of the project the Component belongs to.

### Request Example
```python
component = valispace.get_component_by_name(unique_name='Fan.Blade', project_name='Fan')
```
```

--------------------------------

### Get Matrix

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a matrix object by its ID.

```APIDOC
## Get Matrix

### Description
Retrieve a matrix object by its ID.

### Method
`valispace.get_matrix(id)`

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the matrix to retrieve.

### Request Example
```python
matrix = valispace.get_matrix(id=57)
```
```

--------------------------------

### Get Vali List

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a list of Valis, with optional filtering by workspace, project, parent, or tag.

```APIDOC
## Get Vali List

### Description
Retrieve a list of Valis, with optional filtering by workspace, project, parent, or tag.

### Method
`valispace.get_vali_list()`

### Parameters
#### Query Parameters
- **workspace_id** (integer) - Optional - Filter by workspace ID.
- **workspace_name** (string) - Optional - Filter by workspace name.
- **project_id** (integer) - Optional - Filter by project ID.
- **project_name** (string) - Optional - Filter by project name.
- **parent_id** (integer) - Optional - Filter by parent ID.
- **parent_name** (string) - Optional - Filter by parent name.
- **tag_id** (integer) - Optional - Filter by tag ID.
- **tag_name** (string) - Optional - Filter by tag name.
- **vali_marked_as_impacted** (string) - Optional - Filter Valis marked as impacted (e.g., '10').

### Request Example
```python
# Get all Valis
valis = valispace.get_vali_list()

# Filter by project name
valis = valispace.get_vali_list(project_name='Saturn_V')
```
```

--------------------------------

### Get Matrix String

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a condensed version of a matrix, containing only Vali IDs and values.

```APIDOC
## Get Matrix String

### Description
Retrieve a condensed version of a matrix, containing only Vali IDs and values.

### Method
`valispace.get_matrix_str(id)`

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the matrix to retrieve.

### Request Example
```python
matrix = valispace.get_matrix_str(id=57)
```
```

--------------------------------

### Get a Specific Component by Unique Name

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a Component object by its unique name within a specified project.

```python
valispace.get_component_by_name(unique_name='Fan.Blade', project_name='Fan')
```

--------------------------------

### request / get / post

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Low-level methods for accessing any REST endpoint not covered by a convenience wrapper. URLs are relative to the deployment's `/rest/` base path.

```APIDOC
## `request(method, url, data=None)` / `get(url)` / `post(url, data)` — Raw REST Access

Low-level methods for any endpoint not covered by a convenience wrapper. The URL is relative to the deployment's `/rest/` base path.

```python
# GET any endpoint
projects = vs.get('project/')
vali_42  = vs.get('valis/42/')

# POST to a custom endpoint
new_req = vs.post('requirements/', {
    'specification': 3,
    'identifier': 'REQ-001',
    'title': 'Mass budget',
    'text': 'Total dry mass shall not exceed 5500 kg.'
})

# PATCH a Vali formula directly
vs.request('PATCH', 'valis/42/', data={'formula': '5300 + 200'})

# DELETE
vs.request('DELETE', 'valis/99/')
```
```

--------------------------------

### Get Component by ID

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a specific Component object with all its properties using its ID.

```APIDOC
## Get Component by ID

### Description
Retrieve a specific Component object with all its properties using its ID.

### Method
`valispace.get_component(id)`

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the Component to retrieve.

### Request Example
```python
component = valispace.get_component(id=1)
```
```

--------------------------------

### Get a Matrix by ID

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a matrix object using its unique ID.

```python
matrix = valispace.get_matrix(id=57)
```

--------------------------------

### Get Vali by Name

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a specific Vali object by its unique name within a project.

```APIDOC
## Get Vali by Name

### Description
Retrieve a specific Vali object by its unique name within a project.

### Method
`valispace.get_vali_by_name(vali_name, project_name)`

### Parameters
#### Query Parameters
- **vali_name** (string) - Required - The unique name of the Vali.
- **project_name** (string) - Required - The name of the project the Vali belongs to.

### Request Example
```python
vali = valispace.get_vali_by_name(vali_name='Blade', project_name='Fan')
```
```

--------------------------------

### Get Vali by ID

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a specific Vali object with all its properties using its ID.

```APIDOC
## Get Vali by ID

### Description
Retrieve a specific Vali object with all its properties using its ID.

### Method
`valispace.get_vali(id)`

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the Vali to retrieve.

### Request Example
```python
vali = valispace.get_vali(id=1)
```
```

--------------------------------

### Update Matrix Cell Formulas

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Patches every Vali in a specified matrix with the formula from the corresponding cell of a supplied 2-D list. The example shows updating a 3-row by 1-column matrix.

```python
# 3-row × 1-column matrix
vs.update_matrix_formulas(id=57, matrix_formula=[
    [9.81],
    [0.0],
    [0.0],
])
```

--------------------------------

### Get a Specific Component by ID

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a Component object with all its properties using its unique ID.

```python
valispace.get_component(id=1)
```

--------------------------------

### Get a Specific Vali by ID

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a Vali object with all its properties using its unique ID.

```python
valispace.get_vali(id=1)
```

--------------------------------

### Get a Specific Vali by Unique Name

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a Vali object by its unique name within a specified project.

```python
valispace.get_vali_by_name(vali_name='Blade', project_name='Fan')
```

--------------------------------

### Get a Condensed Matrix by ID

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a condensed version of a matrix, containing only Vali IDs and their values, using its unique ID.

```python
matrix = valispace.get_matrix_str(id=57)
```

--------------------------------

### Get Only the Numeric Value of a Vali

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Efficiently retrieves only the computed numeric value of a Vali by its ID, without fetching the entire Vali object. This is useful for quick value checks.

```python
mass = vs.get_vali_value(id=42)
print(f"Mass: {mass} kg")  # Mass: 5200.0 kg
```

--------------------------------

### Initialize API

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Initialize the Valispace API with your Valispace URL, username, and password, or use a session token.

```APIDOC
## Initialize API

### Description
Initialize the Valispace API with your Valispace URL, username, and password, or use a session token.

### Method
`valispace.API()`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **url** (string) - Required - The URL of your Valispace deployment.
- **username** (string) - Optional - Your Valispace username.
- **password** (string) - Optional - Your Valispace password.
- **session_token** (string) - Optional - Your Valispace session token.

### Request Example
```python
# Using username and password
valispace = valispace.API(url='https://demo.valispace.com', username='your_user_name', password='******')

# Using session token
valispace = valispace.API(url='https://demo.valispace.com', session_token="Bearer your_session_token")
```
```

--------------------------------

### Create Dataset and Set Values

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Create a new dataset for a given Vali ID and set its values. The data is provided as a list of lists.

```python
vali_id = 1

data = [
    [1, 2],
    [3, 4],
    [5, 6],
]

valispace.create_dataset_and_set_values(vali_id, data)
```

--------------------------------

### Import and Initialize Valispace API

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Import the valispace API module and initialize it. Authentication can be done via URL, username, password, or session token.

```python
import valispace
```

```python
valispace = valispace.API()
```

```python
valispace = valispace.API(url='https://demo.valispace.com', username='your_user_name', password='******')
```

```python
valispace = valispace.API(url='https://demo.valispace.com', session_token="Bearer your_session_token")
```

--------------------------------

### Create Dataset and Set Values

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Create a dataset for a Vali and set its values.

```APIDOC
## Create Dataset and Set Values

### Description
Create a dataset for a Vali and set its values.

### Method
`valispace.create_dataset_and_set_values(vali_id, data)`

### Parameters
#### Path Parameters
- **vali_id** (integer) - Required - The ID of the Vali for which to create the dataset.
- **data** (list of lists) - Required - A list of lists representing the dataset values.

### Request Example
```python
vali_id = 1
data = [
    [1, 2],
    [3, 4],
    [5, 6],
]
valispace.create_dataset_and_set_values(vali_id, data)
```
```

--------------------------------

### Fetch Requirements or Specifications for a Project

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Fetches all requirements or specifications associated with a given project ID. The output for specifications includes 'id' and 'title', while requirements include 'identifier', 'title', and 'text'.

```python
specs = vs.get_specifications(project_id=1)
for spec in specs:
    print(spec['id'], spec['title'])

reqs = vs.get_requirements(project_id=1)
for req in reqs:
    print(req['identifier'], req['title'], req['text'])
```

--------------------------------

### create_dataset_and_set_values(vali_id, input_data) — Create and Populate a Dataset

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Converts a specified Vali into a dataset type and populates it with provided data points. Returns the ID of the newly created dataset.

```APIDOC
## `create_dataset_and_set_values(vali_id, input_data)` — Create and Populate a Dataset

Converts a Vali to a dataset type and populates it with rows of `[x, y, ...]` data points.

```python
vali_id = 88

data = [
    [0.0,  0.0],
    [1.0,  9.81],
    [2.0, 19.62],
    [3.0, 29.43],
]

dataset_id = vs.create_dataset_and_set_values(vali_id, data)
print(f"Created dataset {dataset_id}")
```
```

--------------------------------

### Import Dataset with Optional Headers into Vali

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Bulk-imports a dataset into a specified Vali, with optional column header labels. The data should be provided as a list of lists. This is useful for populating Valis with time-series or experimental data.

```python
vs.vali_import_dataset(
    vali_id=88,
    data=[
        [0,     0.00],
        [1000,  9.81],
        [2000, 19.62],
        [3000, 29.43],
    ],
    headers=['time_ms', 'acceleration']
)
```

--------------------------------

### List All Vali IDs and Names

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Generates a list of lightweight dictionaries, each containing an ID and name for all Valis. This can be optionally scoped to a specific project, useful for creating lookup tables without fetching full Vali objects.

```python
# All Valis in the deployment
all_names = vs.get_vali_names()
# [{"id": 1, "name": "Fan.Blade.Mass"}, {"id": 2, "name": "Fan.Blade.Area"}, ...]

# Scoped to one project
names = vs.get_vali_names(project_name='Rocket__SaturnV')
for entry in names:
    print(entry['id'], entry['name'])
```

--------------------------------

### Import Dataset with Valispace API

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Use `vali_import_dataset` to import a dataset. The 'name' fields should never be repeated.

```python
valispace.vali_import_dataset(vali_id, [
    [435, 5],
    [67567, 34],
    [89564, 567830],
    [2345, 5687],
    [2345, 678],
])
```

--------------------------------

### general_prompt

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Sends a custom AI prompt to the Vali Assistant to batch-update a specified field across multiple objects.

```APIDOC
## `general_prompt(...)` — Vali AI Assistant

Sends a custom AI prompt to the Vali Assistant to batch-update a specified field across multiple objects.

```python
result = vs.general_prompt(
    custom_prompt='Write a concise engineering description for this component.',
    model='component',
    field='description',
    objects_ids=[7, 8, 9, 10],
    parallel=True,
    replace_valis_by_id=True,
)
```
```

--------------------------------

### Create Dataset and Set Values

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Converts a Vali to a dataset type and populates it with rows of data points. The function returns the ID of the newly created dataset. Ensure the data is provided as a list of lists, where each inner list represents a row of `[x, y, ...]` values.

```python
vali_id = 88

data = [
    [0.0,  0.0],
    [1.0,  9.81],
    [2.0, 19.62],
    [3.0, 29.43],
]

dataset_id = vs.create_dataset_and_set_values(vali_id, data)
print(f"Created dataset {dataset_id}")
```

--------------------------------

### Create / Update Dataset

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

This method allows you to import or update dataset information in Valispace. It takes a vali ID and a list of data pairs.

```APIDOC
## Create / Update Dataset

### Description
Imports or updates a dataset in Valispace.

### Method
`vali_import_dataset`

### Parameters
- **vali_id** (integer) - Required - The ID of the vali to associate the dataset with.
- **data** (list of lists) - Required - A list where each inner list contains two elements: a component ID and a value.
```

--------------------------------

### Use Vali AI Assistant for Batch Updates

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Send a custom AI prompt to batch-update a specified field across multiple objects. Requires specifying the prompt, model, field, object IDs, and update behavior.

```python
result = vs.general_prompt(
    custom_prompt='Write a concise engineering description for this component.',
    model='component',
    field='description',
    objects_ids=[7, 8, 9, 10],
    parallel=True,
    replace_valis_by_id=True,
)
```

--------------------------------

### List Projects with Optional Workspace Filter

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Returns all projects in the Valispace instance, or optionally filters projects by a specified workspace name or ID. The output includes the ID and name of each project.

```python
all_projects = vs.get_project_list()

ws_projects = vs.get_project_list(workspace_name='Default Workspace')
for p in ws_projects:
    print(p['id'], p['name'])
```

--------------------------------

### Fetch Matrices (Full Objects or Condensed)

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Retrieves matrix data. `get_matrix` returns a 2-D list of full Vali objects, while `get_matrix_str` returns a condensed form with only Vali IDs and values per cell. Accessing the 'value' key is demonstrated for the condensed format.

```python
# Full Vali objects per cell
matrix = vs.get_matrix(id=57)
for row in matrix:
    for cell in row:
        print(cell['name'], cell['value'])

# Condensed — IDs and values only
matrix_str = vs.get_matrix_str(id=57)
# [[{"vali": 101, "value": 2.1}, {"vali": 102, "value": 0.0}], ...]
print(matrix_str[0][0]['value'])
```

--------------------------------

### get_vali_names(project_name=None)

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Returns a list of dictionaries, each containing the ID and name of a Vali. This can be scoped to a specific project or retrieve all Valis in the deployment.

```APIDOC
## get_vali_names(project_name=None)

### Description
Returns a lightweight list of `{id, name}` dicts for all Valis, optionally scoped to a project. Useful for building lookup tables without fetching full objects.

### Parameters
#### Query Parameters
- **project_name** (str) - Optional - The name of the project to scope the search to.

### Response
#### Success Response (200)
- **id** (int) - The unique ID of the Vali.
- **name** (str) - The display name of the Vali.

### Request Example
```python
# All Valis in the deployment
all_names = vs.get_vali_names()
# Expected output: [{'id': 1, 'name': 'Fan.Blade.Mass'}, {'id': 2, 'name': 'Fan.Blade.Area'}, ...]

# Scoped to one project
names = vs.get_vali_names(project_name='Rocket__SaturnV')
for entry in names:
    print(entry['id'], entry['name'])
```
```

--------------------------------

### Fetch a Vali by Name and Project

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Looks up a Vali by its display name within a specific project. Returns the full Vali JSON object, including its ID and value.

```python
vali = vs.get_vali_by_name(
    vali_name='CommandModule.Mass',
    project_name='Rocket__SaturnV'
)
print(vali['id'])     # e.g. 42
print(vali['value'])  # e.g. 5200.0
```

--------------------------------

### Filter Components by Project Name

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a list of Components that belong to a specific project, identified by its name.

```python
valispace.get_component_list(project_name='Fan')
```

--------------------------------

### get_all_data(type)

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Fetches all objects of a specified type (component, vali, textvali, or tag) from Valispace. Returns a dictionary keyed by the object's string ID.

```APIDOC
## `get_all_data(type)` — Fetch All Objects of a Given Type

Returns a dict keyed by string ID for all objects of the requested type: `'component'`, `'vali'`, `'textvali'`, or `'tag'`.

```python
all_valis = vs.get_all_data(type='vali')
# {"1": {"id": 1, "name": "...", ...}, "2": {...}, ...}

all_components = vs.get_all_data(type='component')
all_tags = vs.get_all_data(type='tag')
```
```

--------------------------------

### Shortcut POST Request

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

A shortcut for making POST requests using the `request` method.

```APIDOC
## Shortcut POST Request

### Description
Shortcut for making a POST request.

### Method
`post`

### Parameters
- **url** (string) - Required - The API endpoint URL.
- **data** (object) - Required - The request body for the POST request.
```

--------------------------------

### get_matrix(id) / get_matrix_str(id) — Fetch Matrices

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Fetches matrix data. `get_matrix` returns a 2-D list of full Vali objects, while `get_matrix_str` returns a condensed form with only Vali IDs and their values.

```APIDOC
## `get_matrix(id)` / `get_matrix_str(id)` — Fetch Matrices

`get_matrix` returns a 2-D list of full Vali objects. `get_matrix_str` returns a condensed form with only `{vali: id, value: float}` entries per cell.

```python
# Full Vali objects per cell
matrix = vs.get_matrix(id=57)
for row in matrix:
    for cell in row:
        print(cell['name'], cell['value'])

# Condensed — IDs and values only
matrix_str = vs.get_matrix_str(id=57)
# [[{"vali": 101, "value": 2.1}, {"vali": 102, "value": 0.0}], ...]
print(matrix_str[0][0]['value'])
```
```

--------------------------------

### get_requirements(project_id) / get_specifications(project_id) — Requirements Management

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Fetches all requirements or specifications associated with a given project ID.

```APIDOC
## `get_requirements(project_id)` / `get_specifications(project_id)` — Requirements Management

Fetches all requirements or specifications for a given project.

```python
specs = vs.get_specifications(project_id=1)
for spec in specs:
    print(spec['id'], spec['title'])

reqs = vs.get_requirements(project_id=1)
for req in reqs:
    print(req['identifier'], req['title'], req['text'])
```
```

--------------------------------

### Post Data to Valispace API

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Post new data (e.g., component or vali) to the Valispace API. The data should be a JSON object.

```python
import valispace
valispace = valispace.API()

# -- Insert new Component --
valispace.post_data(type='component', data="""{ 
        "name": "component_name",
        "description": "Insert description here",
        "parent": null,
        "project": 25,
        "tags": [30, 31, 32]
    }""")

# -- Insert new Vali --
valispace.post_data(type='vali', data="""{ 
        "parent": 438,
        "shortname": "mass",
        "description": "",
        "unit": "kg",
        "formula": "5",
        "minimum": null,
        "maximum": null,
        "margin_minus": "0",
        "margin_plus": "0",
        "uses_default_formula": false,
        "reference": "",
        "type": null
    }""")
```

--------------------------------

### vali_import_dataset(vali_id, data, headers=None) — Import Dataset with Headers

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Bulk-imports a dataset into a specified Vali, with an option to include column header labels.

```APIDOC
## `vali_import_dataset(vali_id, data, headers=None)` — Import Dataset with Headers

Bulk-imports a dataset into a Vali, with optional column header labels.

```python
vs.vali_import_dataset(
    vali_id=88,
    data=[
        [0,     0.00],
        [1000,  9.81],
        [2000, 19.62],
        [3000, 29.43],
    ],
    headers=['time_ms', 'acceleration']
)
```
```

--------------------------------

### Filter Valis by Project Name

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a list of Valis that belong to a specific project, identified by its name.

```python
valispace.get_vali_list(project_name='Saturn_V')
```

--------------------------------

### get_project(id) / get_project_by_name(name) — Fetch Projects

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Retrieves a project by its unique ID or its name.

```APIDOC
## `get_project(id)` / `get_project_by_name(name)` — Fetch Projects

Retrieves a project by ID or name.

```python
project = vs.get_project(id=1)
print(project['name'])

projects = vs.get_project_by_name(name='Rocket__SaturnV')
print(projects[0]['id'])
```
```

--------------------------------

### Fetch Projects by ID or Name

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Retrieves a project by its numeric ID or by its name. Note that `get_project_by_name` returns a list, as project names may not be unique across all workspaces.

```python
project = vs.get_project(id=1)
print(project['name'])

projects = vs.get_project_by_name(name='Rocket__SaturnV')
print(projects[0]['id'])
```

--------------------------------

### Fetch All Objects of a Given Type

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Returns a dictionary keyed by string ID for all objects of the specified type. Supported types are 'component', 'vali', 'textvali', or 'tag'.

```python
all_valis = vs.get_all_data(type='vali')
# {"1": {"id": 1, "name": "...", ...}, "2": {...}, ...}

all_components = vs.get_all_data(type='component')
all_tags = vs.get_all_data(type='tag')
```

--------------------------------

### Post Data

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Post new data to Valispace, such as creating a new component or vali.

```APIDOC
## Post Data

### Description
Post new data to Valispace, such as creating a new component or vali.

### Method
`valispace.post_data(type, data)`

### Parameters
#### Query Parameters
- **type** (string) - Required - The type of data to post (e.g., 'component', 'vali').
- **data** (JSON object) - Required - The data to be posted, formatted as a JSON object.

### Request Example
```python
import json

# Insert new Component
component_data = {
    "name": "component_name",
    "description": "Insert description here",
    "parent": null,
    "project": 25,
    "tags": [30, 31, 32]
}
valispace.post_data(type='component', data=json.dumps(component_data))

# Insert new Vali
vali_data = {
    "parent": 438,
    "shortname": "mass",
    "description": "",
    "unit": "kg",
    "formula": "5",
    "minimum": null,
    "maximum": null,
    "margin_minus": "0",
    "margin_plus": "0",
    "uses_default_formula": false,
    "reference": "",
    "type": null
}
valispace.post_data(type='vali', data=json.dumps(vali_data))
```
```

--------------------------------

### Fetch Components by ID or Name

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Retrieves a component by its numeric ID or by its unique hierarchical name within a project. Ensure the project name is unique if using `get_component_by_name`.

```python
# By ID
comp = vs.get_component(id=7)
print(comp['name'])         # "CommandModule"
print(comp['unique_name'])  # "CommandModule"
print(comp['children'])     # [8, 9, 10]

# By unique name
comp = vs.get_component_by_name(
    unique_name='ApolloSpacecraft.CommandModule',
    project_name='Rocket__SaturnV'
)
print(comp['id'])
```

--------------------------------

### Filter Components by Project, Parent, or Tag

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Returns a filtered list of components. Can filter by project name, parent component ID, or tag name. Iterating through the results allows access to each component's ID and unique name.

```python
# All components in a project
comps = vs.get_component_list(project_name='Rocket__SaturnV')

# All direct children of a parent component
children = vs.get_component_list(parent_id=5)

# By tag
tagged = vs.get_component_list(tag_name='structural')

for c in comps:
    print(c['id'], c['unique_name'])
```

--------------------------------

### Make Custom API Request with Valispace API

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Use the `request` method for custom API calls not covered by specific methods. Handles potential errors during the request.

```python
try:
    v = valispace.API('http://demo.valispace.com/', 'user', 'pass')
    projects = v.request('GET', 'project/')
except:
    print('Error')
```

--------------------------------

### Filter Components by Workspace Name

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a list of Components that belong to a specific workspace, identified by its name.

```python
valispace.get_component_list(workspace_name='Default Workspace')
```

--------------------------------

### Filter Components by Project ID

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a list of Components that belong to a specific project, identified by its ID.

```python
valispace.get_component_list(project_id=1)
```

--------------------------------

### Insert New Textvali with Valispace API

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Use `post_data` to insert a new textvali. Ensure the 'name' field is unique to avoid errors.

```python
valispace.post_data(type='textvali', data="""
{
        "shortname": "Message",
        "text": "Message text",
        "parent": 438
    }
""")
```

--------------------------------

### Filter Projects by Workspace Name

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a list of Projects that belong to a specific workspace, identified by its name.

```python
valispace.get_project_list(workspace_name='Default Workspace')
```

--------------------------------

### get_folders / get_groups

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Retrieves the folder and group hierarchy used to organize requirements within a project.

```APIDOC
## `get_folders(project_id)` / `get_groups(project_id)` — Requirements Structure

Returns the folder and group hierarchy used to organise requirements within a project.

```python
folders = vs.get_folders(project_id=1)
groups  = vs.get_groups(project_id=1)
```
```

--------------------------------

### Filter Valis by Project ID

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a list of Valis that belong to a specific project, identified by its ID.

```python
valispace.get_vali_list(project_id=1)
```

--------------------------------

### get_vali_by_name(vali_name, project_name)

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Retrieves a Vali object by its display name and the name of the project it belongs to. This is useful for accessing Valis when their ID is not known.

```APIDOC
## get_vali_by_name(vali_name, project_name)

### Description
Looks up a Vali using its display name and the containing project name. Returns the full Vali JSON object.

### Parameters
#### Query Parameters
- **vali_name** (str) - Required - The display name of the Vali.
- **project_name** (str) - Required - The name of the project containing the Vali.

### Response
#### Success Response (200)
- **id** (int) - The unique ID of the Vali.
- **value** (float) - The computed numeric value of the Vali.

### Request Example
```python
vali = vs.get_vali_by_name(
    vali_name='CommandModule.Mass',
    project_name='Rocket__SaturnV'
)
print(vali['id'])
print(vali['value'])
```
```

--------------------------------

### Filter Valis by Workspace Name

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a list of Valis that belong to a specific workspace, identified by its name.

```python
valispace.get_vali_list(workspace_name='Default Workspace')
```

--------------------------------

### Insert New Tag with Valispace API

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Use `post_data` to insert a new tag. The 'name' field must be unique.

```python
valispace.post_data(type='tag', data="""
{
        "name": "white-tag",
        "color": "#FFFFFF"
    }
""")
```

--------------------------------

### Custom Request

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Allows making custom HTTP requests to the Valispace API for operations not covered by specific methods.

```APIDOC
## Custom Request

### Description
Make custom GET, POST, or DELETE requests to the Valispace API.

### Method
`request`

### Parameters
- **method** (string) - Required - The HTTP method (e.g., 'GET', 'POST', 'DELETE').
- **url** (string) - Required - The API endpoint URL (e.g., 'project/').
- **data** (object) - Optional - The request body for POST requests.
```

--------------------------------

### Create New Objects (Component, Vali, TextVali, Tag)

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Creates new objects of specified types ('component', 'vali', 'textvali', or 'tag') from JSON data. The function returns the JSON of the newly created object. Ensure correct JSON formatting for the 'data' parameter.

```python
# New component
vs.post_data(type='component', data='{
    "name": "PropulsionSystem",
    "description": "Main propulsion assembly",
    "parent": null,
    "project": 1,
    "tags": [5]
}')

# New Vali
vs.post_data(type='vali', data='{
    "parent": 10,
    "shortname": "Thrust",
    "description": "Engine thrust force",
    "unit": "N",
    "formula": "7500000",
    "minimum": 7000000,
    "maximum": 8000000,
    "margin_minus": "0",
    "margin_plus": "0",
    "uses_default_formula": false,
    "reference": "",
    "type": null
}')

# New TextVali
vs.post_data(type='textvali', data='{
    "shortname": "Material",
    "text": "Aluminium 7075-T6",
    "parent": 10
}')

# New Tag
vs.post_data(type='tag', data='{
    "name": "reviewed",
    "color": "#00FF00"
}')
```

--------------------------------

### Filter Valis by Criteria

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Retrieves a list of Vali objects that match specified filter criteria, such as project name, parent component ID, tag, or whether the Vali is marked as impacted by another Vali.

```python
# By project name
valis = vs.get_vali_list(project_name='Rocket__SaturnV')

# By parent component ID
valis = vs.get_vali_list(parent_id=10)

# By tag
valis = vs.get_vali_list(tag_name='thermal')

# By vali marked as impacted (pass the impacting vali's ID)
valis = vs.get_vali_list(vali_marked_as_impacted=4)

for v in valis:
    print(v['name'], v['value'], v['unit'])
```

--------------------------------

### Fuzzy-Search Valis by Name

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Finds a Vali using an approximate name string, which is useful when the exact full path name is not known. Returns the matching Vali's name and value.

```python
result = vs.fuzzysearch_vali('CmdMod Mass')
print(result['name'])   # e.g. "CommandModule.Mass"
print(result['value'])  # e.g. 5200.0
```

--------------------------------

### Insert New Tag

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

This method allows you to insert new tags into Valispace. Tags can be used for categorization and have a name and color.

```APIDOC
## Insert New Tag

### Description
Inserts a new tag into Valispace.

### Method
`post_data`

### Parameters
- **type** (string) - Required - The type of data to insert, e.g., 'tag'.
- **data** (string) - Required - A JSON string containing the tag data.
  - **name** (string) - Required - The name of the tag. Must be unique.
  - **color** (string) - Required - The color of the tag in hexadecimal format (e.g., '#FFFFFF').
```

--------------------------------

### Filter Components by Tag Name

Source: https://github.com/valispace/valispacepythonapi/blob/master/README.md

Retrieve a list of Components that are associated with a specific tag, identified by its name.

```python
valispace.get_component_list(tag_name='example_tag')
```

--------------------------------

### get_project_list(workspace_id=None, workspace_name=None) — List Projects

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Returns a list of all projects, with an option to filter by a specific workspace using its ID or name.

```APIDOC
## `get_project_list(workspace_id=None, workspace_name=None)` — List Projects

Returns all projects, optionally filtered by workspace.

```python
all_projects = vs.get_project_list()

ws_projects = vs.get_project_list(workspace_name='Default Workspace')
for p in ws_projects:
    print(p['id'], p['name'])
```
```

--------------------------------

### post_data(type, data) — Create New Objects

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Creates new objects of specified types (component, vali, textvali, or tag) from JSON data. Returns the JSON of the newly created object.

```APIDOC
## `post_data(type, data)` — Create New Objects

Creates a new `component`, `vali`, `textvali`, or `tag` from a JSON string or dict. Returns the created object's JSON.

```python
# New component
vs.post_data(type='component', data="""{
    "name": "PropulsionSystem",
    "description": "Main propulsion assembly",
    "parent": null,
    "project": 1,
    "tags": [5]
}""" ) 

# New Vali
vs.post_data(type='vali', data="""{
    "parent": 10,
    "shortname": "Thrust",
    "description": "Engine thrust force",
    "unit": "N",
    "formula": "7500000",
    "minimum": 7000000,
    "maximum": 8000000,
    "margin_minus": "0",
    "margin_plus": "0",
    "uses_default_formula": false,
    "reference": "",
    "type": null
}""" )

# New TextVali
vs.post_data(type='textvali', data="""{
    "shortname": "Material",
    "text": "Aluminium 7075-T6",
    "parent": 10
}""" )

# New Tag
vs.post_data(type='tag', data="""{
    "name": "reviewed",
    "color": "#00FF00"
}""" )
```
```

--------------------------------

### get_vali(id)

Source: https://context7.com/valispace/valispacepythonapi/llms.txt

Fetches a single Vali object by its unique numeric ID. It returns the full JSON representation of the Vali and raises an exception if a non-integer ID is provided.

```APIDOC
## get_vali(id)

### Description
Returns a full JSON object for the Vali whose numeric ID matches the argument. Raises an exception if a non-integer is passed.

### Parameters
#### Path Parameters
- **id** (int) - Required - The unique numeric ID of the Vali to fetch.

### Response
#### Success Response (200)
- **name** (str) - The display name of the Vali.
- **value** (float) - The computed numeric value of the Vali.
- **unit** (str) - The unit of measurement for the Vali's value.
- **formula** (str) - The formula used to compute the Vali's value.

### Request Example
```python
vali = vs.get_vali(id=42)
print(vali['name'])
print(vali['value'])
print(vali['unit'])
print(vali['formula'])
```
```