# RestClient

## _class_ [**tinker.RestClient**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L28)( _holder_)

Client for REST API operations like listing checkpoints and metadata.

The RestClient provides access to various REST endpoints for querying model information, checkpoints, and other resources. You typically get one by calling `service_client.create_rest_client()`.

**Key methods:**

- list\_checkpoints() - list available model checkpoints (both training and sampler)
- list\_user\_checkpoints() - list all checkpoints across all user's training runs
- get\_training\_run() - get model information and metadata as ModelEntry
- delete\_checkpoint() - delete an existing checkpoint for a training run
- get\_checkpoint\_archive\_url() - get signed URL to download checkpoint archive
- publish\_checkpoint\_from\_tinker\_path() - publish a checkpoint to make it public
- unpublish\_checkpoint\_from\_tinker\_path() - unpublish a checkpoint to make it private
- set\_checkpoint\_ttl\_from\_tinker\_path() - set or remove TTL on a checkpoint
- assign\_session\_project() - move a session into a project

```python
rest_client = service_client.create_rest_client()
training_run = rest_client.get_training_run("run-id").result()
print(f"Training Run: {training_run.training_run_id}, LoRA: {training_run.is_lora}")
checkpoints = rest_client.list_checkpoints("run-id").result()
print(f"Found {len(checkpoints.checkpoints)} checkpoints")
for checkpoint in checkpoints.checkpoints:
    print(f"  {checkpoint.checkpoint_type}: {checkpoint.checkpoint_id}")
```

**Parameters:**

- [**holder**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L61) ( _[InternalClientHolder](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/internal_client_holder.py#L185)_) – Internal client managing HTTP connections and async operations

### [**get\_training\_run**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L86)( _training\_run\_id_, _access\_scope='owned'_)

Get training run info.

**Parameters:**

- [**training\_run\_id**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L88) ( _types. [ModelID](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/types/model_id.py#L5)_) – The training run ID to get information for
- [**access\_scope**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L89) ( _Literal['owned', 'accessible']_, default: 'owned')

**Returns:** A `Future` containing the training run information

```python
future = rest_client.get_training_run("run-id")
response = future.result()
print(f"Training Run ID: {response.training_run_id}, Base: {response.base_model}")
```

_Async variant:_`get_training_run_async()`

### [**get\_training\_run\_by\_tinker\_path**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L117)( _tinker\_path_, _access\_scope='owned'_)

Get training run info.

**Parameters:**

- [**tinker\_path**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L118) ( _str_) – The tinker path to the checkpoint
- [**access\_scope**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L118) ( _Literal['owned', 'accessible']_, default: 'owned')

**Returns:** A `Future` containing the training run information

```python
future = rest_client.get_training_run_by_tinker_path("tinker://run-id/weights/checkpoint-001")
response = future.result()
print(f"Training Run ID: {response.training_run_id}, Base: {response.base_model}")
```

_Async variant:_`get_training_run_by_tinker_path_async()`

### [**get\_weights\_info\_by\_tinker\_path**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L157)( _tinker\_path_)

Get checkpoint information from a tinker path.

**Parameters:**

- [**tinker\_path**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L158) ( _str_) – The tinker path to the checkpoint

**Returns:** An [`APIFuture`](https://tinker-docs.thinkingmachines.ai/tinker/api-reference/apifuture/) containing the checkpoint information. The future is awaitable.

```python
future = rest_client.get_weights_info_by_tinker_path("tinker://run-id/weights/checkpoint-001")
response = future.result()  # or await future
print(f"Base Model: {response.base_model}, LoRA Rank: {response.lora_rank}")
```

### [**list\_training\_runs**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L221)( _limit=20_, _offset=0_, _access\_scope='owned'_, _project\_id=None_)

List training runs with pagination support.

**Parameters:**

- [**limit**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L223) ( _int_, default: '20') – Maximum number of training runs to return (default 20)
- [**offset**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L224) ( _int_, default: '0') – Offset for pagination (default 0)
- [**access\_scope**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L225) ( _Literal['owned', 'accessible']_, default: 'owned')
- [**project\_id**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L226) ( _str | None_, default: 'None') – If provided, only return training runs in this project

**Returns:** A `Future` containing the [`TrainingRunsResponse`](https://tinker-docs.thinkingmachines.ai/tinker/api-reference/types/trainingrunsresponse/) with training runs and cursor info

```python
future = rest_client.list_training_runs(limit=50)
response = future.result()
print(f"Found {len(response.training_runs)} training runs")
print(f"Total: {response.cursor.total_count}")
# Get next page
next_page = rest_client.list_training_runs(limit=50, offset=50)
# Only runs in a given project
project_runs = rest_client.list_training_runs(project_id="my-project-id").result()
```

_Async variant:_`list_training_runs_async()`

### [**list\_checkpoints**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L289)( _training\_run\_id_)

List available checkpoints (both training and sampler).

**Parameters:**

- [**training\_run\_id**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L290) ( _types. [ModelID](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/types/model_id.py#L5)_) – The training run ID to list checkpoints for

**Returns:** A `Future` containing the [`CheckpointsListResponse`](https://tinker-docs.thinking-machines.ai/tinker/api-reference/types/checkpointslistresponse/) with available checkpoints

```python
future = rest_client.list_checkpoints("run-id")
response = future.result()
for checkpoint in response.checkpoints:
    if checkpoint.checkpoint_type == "training":
        print(f"Training checkpoint: {checkpoint.checkpoint_id}")
    elif checkpoint.checkpoint_type == "sampler":
        print(f"Sampler checkpoint: {checkpoint.checkpoint_id}")
```

_Async variant:_`list_checkpoints_async()`

### [**get\_checkpoint\_archive\_url**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L356)( _training\_run\_id_, _checkpoint\_id_)

Get signed URL to download checkpoint archive.

**Parameters:**

- [**training\_run\_id**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L357) ( _types. [ModelID](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/types/model_id.py#L5)_) – The training run ID to download weights for
- [**checkpoint\_id**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L357) ( _str_) – The checkpoint ID to download

**Returns:** A `Future` containing the [`CheckpointArchiveUrlResponse`](https://tinker-docs.thinking-machines.ai/tinker/api-reference/types/checkpointarchiveurlresponse/) with signed URL and expiration

```python
future = rest_client.get_checkpoint_archive_url("run-id", "checkpoint-123")
response = future.result()
print(f"Download URL: {response.url}")
print(f"Expires at: {response.expires_at}")
# Use the URL to download the archive with your preferred HTTP client
```

_Async variant:_`get_checkpoint_archive_url_async()`

### [**delete\_checkpoint**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L405)( _training\_run\_id_, _checkpoint\_id_)

Delete a checkpoint for a training run.

**Parameters:**

- [**training\_run\_id**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L406) ( _types. [ModelID](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/types/model_id.py#L5)_)  
- [**checkpoint\_id**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L406) ( _str_)

**Returns:** _ConcurrentFuture[None]_

_Async variant:_`delete_checkpoint_async()`

### [**delete\_checkpoint\_from\_tinker\_path**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L422)( _tinker\_path_)

Delete a checkpoint referenced by a tinker path.

**Parameters:**

- [**tinker\_path**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L422) ( _str_)

**Returns:** _ConcurrentFuture[None]_

_Async variant:_`delete_checkpoint_from_tinker_path_async()`

### [**get\_audit\_log**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L441)( _event\_type='all'_, _day=None_)

Get an audit log of events for the caller's organization.

Requires the tinker-admin RBAC role (VIEW\_AUDIT\_LOG capability).

**Parameters:**

- [**event\_type**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L443) ( _Literal['all', 'checkpoints']_, default: 'all') – Type of events to include. "all" and "checkpoints" are currently equivalent. Defaults to "all".
- [**day**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L444) ( _date | None_, default: 'None') – The date to query (default: today). The window covers midnight to midnight UTC.

**Returns:** A `Future` containing the [`AuditLogResponse`](https://tinker-docs.thinking-machines.ai/tinker/api-reference/types/auditlogresponse/) with audit log entries

```python
from datetime import date

future = rest_client.get_audit_log()
response = future.result()
print(f"Found {len(response.entries)} audit entries")
for entry in response.entries:
    print(f"  {entry.timestamp}: {entry.event} ({entry.tinker_path})")

# Query a specific day
future = rest_client.get_audit_log(day=date(2025, 1, 15))
```

_Async variant:_`get_audit_log_async()`

### [**get\_checkpoint\_archive\_url\_from\_tinker\_path**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L503)( _tinker\_path_)

Get signed URL to download checkpoint archive.

**Parameters:**

- [**tinker\_path**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L504) ( _str_) – The tinker path to the checkpoint

_Async variant:_`get_checkpoint_archive_url_from_tinker_path_async()`

### [**publish\_checkpoint\_from\_tinker\_path**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L548)( _tinker\_path_)

Publish a checkpoint referenced by a tinker path to make it publicly accessible.

Only the exact owner of the training run can publish checkpoints.
Published checkpoints can be unpublished using the unpublish\_checkpoint\_from\_tinker\_path method.

**Parameters:**

- [**tinker\_path**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L548) ( _str_) – The tinker path to the checkpoint (e.g., "tinker://run-id/weights/0001")

**Returns:** A `Future` that completes when the checkpoint is published

```python
future = rest_client.publish_checkpoint_from_tinker_path("tinker://run-id/weights/0001")
future.result()  # Wait for completion
print("Checkpoint published successfully")
```

_Async variant:_`publish_checkpoint_from_tinker_path_async()`

### [**unpublish\_checkpoint\_from\_tinker\_path**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L605)( _tinker\_path_)

Unpublish a checkpoint referenced by a tinker path to make it private again.

Only the exact owner of the training run can unpublish checkpoints.
This reverses the effect of publishing a checkpoint.

**Parameters:**

- [**tinker\_path**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L605) ( _str_) – The tinker path to the checkpoint (e.g., "tinker://run-id/weights/0001")

**Returns:** A `Future` that completes when the checkpoint is unpublished

```python
future = rest_client.unpublish_checkpoint_from_tinker_path("tinker://run-id/weights/0001")
future.result()  # Wait for completion
print("Checkpoint unpublished successfully")
```

_Async variant:_`unpublish_checkpoint_from_tinker_path_async()`

### [**set\_checkpoint\_ttl\_from\_tinker\_path**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L663)( _tinker\_path_, _ttl\_seconds_)

Set or remove the TTL on a checkpoint referenced by a tinker path.

If ttl\_seconds is provided, the checkpoint will expire after that many seconds from now.
If ttl\_seconds is None, any existing expiration will be removed.

**Parameters:**

- [**tinker\_path**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L664) ( _str_) – The tinker path to the checkpoint (e.g., "tinker://run-id/weights/0001")
- [**ttl\_seconds**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L664) ( _int | None_) – Number of seconds until expiration, or None to remove TTL

**Returns:** A `Future` that completes when the TTL is set

```python
future = rest_client.set_checkpoint_ttl_from_tinker_path("tinker://run-id/weights/0001", 86400)
future.result()  # Wait for completion
print("Checkpoint TTL set successfully")
```

_Async variant:_`set_checkpoint_ttl_from_tinker_path_async()`

### [**list\_user\_checkpoints**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L727)( _limit=100_, _offset=0_)

List all checkpoints for the current user across all their training runs.

This method retrieves checkpoints from all training runs owned by the authenticated user,
sorted by time (newest first). It supports pagination for efficiently handling large numbers of checkpoints.

**Parameters:**

- [**limit**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L728) ( _int_, default: '100') – Maximum number of checkpoints to return (default 100)
- [**offset**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L728) ( _int_, default: '0') – Offset for pagination (default 0)

**Returns:** A `Future` containing the [`CheckpointsListResponse`](https://tinker-docs.thinking-machines.ai/tinker/api-reference/types/checkpointslistresponse/) with checkpoints and cursor info

```python
future = rest_client.list_user_checkpoints(limit=50)
response = future.result()
print(f"Found {len(response.checkpoints)} checkpoints")
print(f"Total: {response.cursor.total_count if response.cursor else 'Unknown'}")
for checkpoint in response.checkpoints:
    print(f"  {checkpoint.training_run_id}/{checkpoint.checkpoint_id}")
# Get next page if there are more checkpoints
if response.cursor and response.cursor.offset + response.cursor.limit < response.cursor.total_count:
    next_page = rest_client.list_user_checkpoints(limit=50, offset=50)
```

_Async variant:_`list_user_checkpoints_async()`

### [**get\_session**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L787)( _session\_id_, _access\_scope='owned'_)

Get session information including all training runs and samplers.

**Parameters:**

- [**session\_id**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L788) ( _str_) – The session ID to get information for
- [**access\_scope**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L788) ( _Literal['owned', 'accessible']_, default: 'owned')

**Returns:** A `Future` containing the [`GetSessionResponse`](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/types/get_session_response.py#L7) with training\_run\_ids and sampler\_ids

```python
future = rest_client.get_session("session-id")
response = future.result()
print(f"Training runs: {len(response.training_run_ids)}")
print(f"Samplers: {len(response.sampler_ids)}")
```

_Async variant:_`get_session_async()`

### [**list\_sessions**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L844)( _limit=20_, _offset=0_, _access\_scope='owned'_)

List sessions with pagination support.

**Parameters:**

- [**limit**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L846) ( _int_, default: '20') – Maximum number of sessions to return (default 20)
- [**offset**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L847) ( _int_, default: '0') – Offset for pagination (default 0)
- [**access\_scope**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L848) ( _Literal['owned', 'accessible']_, default: 'owned')

**Returns:** A `Future` containing the [`ListSessionsResponse`](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/types/list_sessions_response.py#L6) with list of session IDs

```python
future = rest_client.list_sessions(limit=50)
response = future.result()
print(f"Found {len(response.sessions)} sessions")
# Get next page
next_page = rest_client.list_sessions(limit=50, offset=50)
```

_Async variant:_`list_sessions_async()`

### [**assign\_session\_project**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L908)( _session\_id_, _project\_id_)

Move a session (and all of its training runs/samplers) into a project.

Use this to attach a previously-created session to a project, or to move
 a session between projects. Clearing the project is not supported — sessions
 cannot be moved out of a project once placed.

**Parameters:**

- [**session\_id**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L908) ( _str_) – The session ID to move
- [**project\_id**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L908) ( _str_) – The destination project ID

**Returns:** A `Future` that completes when the session has been moved

```python
future = rest_client.assign_session_project("session-id", "project-id")
future.result()
```

_Async variant:_`assign_session_project_async()`

### [**get\_sampler**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L941)( _sampler\_id_)

Get sampler information.

**Parameters:**

- [**sampler\_id**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/rest_client.py#L941) ( _str_) – The sampler ID (sampling\_session\_id) to get information for

**Returns:** An [`APIFuture`](https://tinker-docs.thinking-machines.ai/tinker/api-reference/apifuture/) containing the [`GetSamplerResponse`](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/types/_pydantic_types/get_sampler_response.py#L4) with sampler details

```python
# Sync usage
future = rest_client.get_sampler("session-id:sample:0")
response = future.result()
print(f"Base model: {response.base_model}")
print(f"Model path: {response.model_path}")

# Async usage
response = await rest_client.get_sampler("session-id:sample:0")
print(f"Base model: {response.base_model}")
```

_Async variant:_`get_sampler_async()`

## Referenced by

- [ServiceClient.create\_rest\_client](https://tinker-docs.thinking-machines.ai/tinker/api-reference/serviceclient/#create_rest_client)