# `Tinkex.RestClient`
[🔗](https://github.com/North-Shore-AI/tinkex/blob/v0.4.0/lib/tinkex/rest_client.ex#L1)

REST client for Tinker API operations.

Provides checkpoint and session management functionality with both
synchronous and asynchronous variants.

## Usage

    {:ok, service_pid} = Tinkex.ServiceClient.start_link(config: config)
    {:ok, rest_client} = Tinkex.ServiceClient.create_rest_client(service_pid)

    # Synchronous API
    {:ok, sessions} = Tinkex.RestClient.list_sessions(rest_client)
    {:ok, checkpoints} = Tinkex.RestClient.list_user_checkpoints(rest_client)

    # Asynchronous API - returns Task.t()
    task = Tinkex.RestClient.list_sessions_async(rest_client)
    {:ok, sessions} = Task.await(task)

    # Parallel requests
    tasks = [
      Tinkex.RestClient.list_sessions_async(rest_client),
      Tinkex.RestClient.list_user_checkpoints_async(rest_client)
    ]
    results = Task.await_many(tasks)

# `t`

```elixir
@type t() :: %Tinkex.RestClient{config: Tinkex.Config.t(), session_id: String.t()}
```

# `delete_checkpoint`

```elixir
@spec delete_checkpoint(t(), String.t()) :: {:ok, map()} | {:error, Tinkex.Error.t()}
```

Delete a checkpoint.

## Examples

    {:ok, _} = RestClient.delete_checkpoint(client, "tinker://run-123/weights/0001")

# `delete_checkpoint`

```elixir
@spec delete_checkpoint(t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, Tinkex.Error.t()}
```

Delete a checkpoint by training run and checkpoint ID.

# `delete_checkpoint_async`

```elixir
@spec delete_checkpoint_async(t(), String.t()) :: Task.t()
```

Async variant of `delete_checkpoint/2`.

Returns a `Task.t()` that resolves to `{:ok, map()} | {:error, Tinkex.Error.t()}`.

# `delete_checkpoint_async`

```elixir
@spec delete_checkpoint_async(t(), String.t(), String.t()) :: Task.t()
```

Async variant of `delete_checkpoint/3`.

Returns a `Task.t()` that resolves to `{:ok, map()} | {:error, Tinkex.Error.t()}`.

# `delete_checkpoint_by_tinker_path`

```elixir
@spec delete_checkpoint_by_tinker_path(t(), String.t()) ::
  {:ok, map()} | {:error, Tinkex.Error.t()}
```

Delete a checkpoint referenced by a tinker path.

Alias for `delete_checkpoint/2` to mirror Python convenience naming.

# `delete_checkpoint_by_tinker_path_async`

```elixir
@spec delete_checkpoint_by_tinker_path_async(t(), String.t()) :: Task.t()
```

Async variant of `delete_checkpoint_by_tinker_path/2`.

# `get_checkpoint_archive_url`

```elixir
@spec get_checkpoint_archive_url(t(), String.t()) ::
  {:ok, Tinkex.Types.CheckpointArchiveUrlResponse.t()}
  | {:error, Tinkex.Error.t()}
```

Get the archive download URL for a checkpoint.

## Examples

    {:ok, response} = RestClient.get_checkpoint_archive_url(client, "tinker://run-123/weights/0001")
    IO.puts(response.url)

# `get_checkpoint_archive_url`

```elixir
@spec get_checkpoint_archive_url(t(), String.t(), keyword()) ::
  {:ok, Tinkex.Types.CheckpointArchiveUrlResponse.t()}
  | {:error, Tinkex.Error.t()}
@spec get_checkpoint_archive_url(t(), String.t(), String.t()) ::
  {:ok, Tinkex.Types.CheckpointArchiveUrlResponse.t()}
  | {:error, Tinkex.Error.t()}
```

Get the archive download URL for a checkpoint by training run and checkpoint ID.

# `get_checkpoint_archive_url`

```elixir
@spec get_checkpoint_archive_url(t(), String.t(), String.t(), keyword()) ::
  {:ok, Tinkex.Types.CheckpointArchiveUrlResponse.t()}
  | {:error, Tinkex.Error.t()}
```

# `get_checkpoint_archive_url_async`

```elixir
@spec get_checkpoint_archive_url_async(t(), String.t()) :: Task.t()
```

Async variant of `get_checkpoint_archive_url/2`.

Returns a `Task.t()` that resolves to `{:ok, CheckpointArchiveUrlResponse.t()} | {:error, Tinkex.Error.t()}`.

# `get_checkpoint_archive_url_async`

```elixir
@spec get_checkpoint_archive_url_async(t(), String.t(), String.t()) :: Task.t()
```

Async variant of `get_checkpoint_archive_url/3`.

Returns a `Task.t()` that resolves to `{:ok, CheckpointArchiveUrlResponse.t()} | {:error, Tinkex.Error.t()}`.

# `get_checkpoint_archive_url_by_tinker_path`

```elixir
@spec get_checkpoint_archive_url_by_tinker_path(t(), String.t()) ::
  {:ok, Tinkex.Types.CheckpointArchiveUrlResponse.t()}
  | {:error, Tinkex.Error.t()}
```

Get the archive download URL for a checkpoint referenced by a tinker path.

Alias for `get_checkpoint_archive_url/2` to mirror Python convenience naming.

# `get_checkpoint_archive_url_by_tinker_path_async`

```elixir
@spec get_checkpoint_archive_url_by_tinker_path_async(t(), String.t()) :: Task.t()
```

Async variant of `get_checkpoint_archive_url_by_tinker_path/2`.

# `get_sampler`

```elixir
@spec get_sampler(t(), String.t()) ::
  {:ok, Tinkex.Types.GetSamplerResponse.t()} | {:error, Tinkex.Error.t()}
```

Get sampler information.

Returns details about a sampler, including the base model and any loaded
custom weights.

## Examples

    {:ok, response} = RestClient.get_sampler(client, "session-id:sample:0")
    IO.inspect(response.base_model)
    IO.inspect(response.model_path)

# `get_sampler_async`

```elixir
@spec get_sampler_async(t(), String.t()) :: Task.t()
```

Async variant of `get_sampler/2`.

Returns a `Task.t()` that resolves to `{:ok, GetSamplerResponse.t()} | {:error, Tinkex.Error.t()}`.

# `get_session`

```elixir
@spec get_session(t(), String.t(), keyword()) ::
  {:ok, Tinkex.Types.GetSessionResponse.t()} | {:error, Tinkex.Error.t()}
```

Get session information.

Returns training run IDs and sampler IDs associated with the session.

## Examples

    {:ok, response} = RestClient.get_session(client, "session-123")
    IO.inspect(response.training_run_ids)
    IO.inspect(response.sampler_ids)

# `get_session_async`

```elixir
@spec get_session_async(t(), String.t(), keyword()) :: Task.t()
```

Async variant of `get_session/2`.

Returns a `Task.t()` that resolves to `{:ok, GetSessionResponse.t()} | {:error, Tinkex.Error.t()}`.

## Examples

    task = RestClient.get_session_async(client, "session-123")
    {:ok, response} = Task.await(task)

# `get_training_run`

```elixir
@spec get_training_run(t(), String.t(), keyword()) ::
  {:ok, Tinkex.Types.TrainingRun.t()} | {:error, Tinkex.Error.t()}
```

Get a training run by ID.

# `get_training_run_async`

```elixir
@spec get_training_run_async(t(), String.t(), keyword()) :: Task.t()
```

Async variant of `get_training_run/2`.

Returns a `Task.t()` that resolves to `{:ok, TrainingRun.t()} | {:error, Tinkex.Error.t()}`.

# `get_training_run_by_tinker_path`

```elixir
@spec get_training_run_by_tinker_path(t(), String.t(), keyword()) ::
  {:ok, Tinkex.Types.TrainingRun.t()} | {:error, Tinkex.Error.t()}
```

Get a training run by tinker path.

# `get_training_run_by_tinker_path_async`

```elixir
@spec get_training_run_by_tinker_path_async(t(), String.t(), keyword()) :: Task.t()
```

Async variant of `get_training_run_by_tinker_path/2`.

Returns a `Task.t()` that resolves to `{:ok, TrainingRun.t()} | {:error, Tinkex.Error.t()}`.

# `get_weights_info_by_tinker_path`

```elixir
@spec get_weights_info_by_tinker_path(t(), String.t()) ::
  {:ok, Tinkex.Types.WeightsInfoResponse.t()} | {:error, Tinkex.Error.t()}
```

Get checkpoint information from a tinker path.

Returns metadata about a checkpoint such as base model and LoRA details.

## Examples

    path = "tinker://run-id/weights/checkpoint-001"
    {:ok, response} = RestClient.get_weights_info_by_tinker_path(client, path)
    IO.inspect(response.base_model)
    IO.inspect(response.is_lora)
    IO.inspect(response.lora_rank)

# `get_weights_info_by_tinker_path_async`

```elixir
@spec get_weights_info_by_tinker_path_async(t(), String.t()) :: Task.t()
```

Async variant of `get_weights_info_by_tinker_path/2`.

Returns a `Task.t()` that resolves to `{:ok, WeightsInfoResponse.t()} | {:error, Tinkex.Error.t()}`.

# `list_checkpoints`

```elixir
@spec list_checkpoints(t(), String.t()) ::
  {:ok, Tinkex.Types.CheckpointsListResponse.t()} | {:error, Tinkex.Error.t()}
```

List checkpoints for a specific training run.

## Examples

    {:ok, response} = RestClient.list_checkpoints(client, "run-123")
    for checkpoint <- response.checkpoints do
      IO.puts(checkpoint.tinker_path)
    end

# `list_checkpoints_async`

```elixir
@spec list_checkpoints_async(t(), String.t()) :: Task.t()
```

Async variant of `list_checkpoints/2`.

Returns a `Task.t()` that resolves to `{:ok, CheckpointsListResponse.t()} | {:error, Tinkex.Error.t()}`.

# `list_sessions`

```elixir
@spec list_sessions(
  t(),
  keyword()
) :: {:ok, Tinkex.Types.ListSessionsResponse.t()} | {:error, Tinkex.Error.t()}
```

List sessions with pagination.

## Options
  * `:limit` - Maximum number of sessions to return (default: 20)
  * `:offset` - Offset for pagination (default: 0)

## Examples

    {:ok, response} = RestClient.list_sessions(client)
    {:ok, response} = RestClient.list_sessions(client, limit: 50, offset: 100)

# `list_sessions_async`

```elixir
@spec list_sessions_async(
  t(),
  keyword()
) :: Task.t()
```

Async variant of `list_sessions/2`.

Returns a `Task.t()` that resolves to `{:ok, ListSessionsResponse.t()} | {:error, Tinkex.Error.t()}`.

## Examples

    task = RestClient.list_sessions_async(client)
    {:ok, response} = Task.await(task)

    task = RestClient.list_sessions_async(client, limit: 50)
    {:ok, response} = Task.await(task)

# `list_training_runs`

```elixir
@spec list_training_runs(
  t(),
  keyword()
) :: {:ok, Tinkex.Types.TrainingRunsResponse.t()} | {:error, Tinkex.Error.t()}
```

List training runs with pagination.

# `list_training_runs_async`

```elixir
@spec list_training_runs_async(
  t(),
  keyword()
) :: Task.t()
```

Async variant of `list_training_runs/2`.

Returns a `Task.t()` that resolves to `{:ok, TrainingRunsResponse.t()} | {:error, Tinkex.Error.t()}`.

# `list_user_checkpoints`

```elixir
@spec list_user_checkpoints(
  t(),
  keyword()
) ::
  {:ok, Tinkex.Types.CheckpointsListResponse.t()} | {:error, Tinkex.Error.t()}
```

List all checkpoints for the current user with pagination.

## Options
  * `:limit` - Maximum number of checkpoints to return (default: 100)
  * `:offset` - Offset for pagination (default: 0)

## Examples

    {:ok, response} = RestClient.list_user_checkpoints(client)
    {:ok, response} = RestClient.list_user_checkpoints(client, limit: 100, offset: 50)

# `list_user_checkpoints_async`

```elixir
@spec list_user_checkpoints_async(
  t(),
  keyword()
) :: Task.t()
```

Async variant of `list_user_checkpoints/2`.

Returns a `Task.t()` that resolves to `{:ok, CheckpointsListResponse.t()} | {:error, Tinkex.Error.t()}`.

# `new`

```elixir
@spec new(String.t(), Tinkex.Config.t()) :: t()
```

Create a new RestClient.

## Parameters
  * `session_id` - The session ID for this client
  * `config` - The Tinkex configuration

# `publish_checkpoint`

```elixir
@spec publish_checkpoint(t(), String.t()) :: {:ok, map()} | {:error, Tinkex.Error.t()}
```

Publish a checkpoint (make it public).

# `publish_checkpoint_async`

```elixir
@spec publish_checkpoint_async(t(), String.t()) :: Task.t()
```

Async variant of `publish_checkpoint/2`.

Returns a `Task.t()` that resolves to `{:ok, map()} | {:error, Tinkex.Error.t()}`.

# `publish_checkpoint_from_tinker_path`

```elixir
@spec publish_checkpoint_from_tinker_path(t(), String.t()) ::
  {:ok, map()} | {:error, Tinkex.Error.t()}
```

Publish a checkpoint referenced by a tinker path.

Alias for `publish_checkpoint/2` to mirror Python convenience naming.

# `publish_checkpoint_from_tinker_path_async`

```elixir
@spec publish_checkpoint_from_tinker_path_async(t(), String.t()) :: Task.t()
```

Async variant of `publish_checkpoint_from_tinker_path/2`.

# `set_checkpoint_ttl_from_tinker_path`

```elixir
@spec set_checkpoint_ttl_from_tinker_path(t(), String.t(), integer() | nil) ::
  {:ok, map()} | {:error, Tinkex.Error.t()}
```

Update checkpoint TTL using a tinker path.

# `set_checkpoint_ttl_from_tinker_path_async`

```elixir
@spec set_checkpoint_ttl_from_tinker_path_async(t(), String.t(), integer() | nil) ::
  Task.t()
```

Async variant of `set_checkpoint_ttl_from_tinker_path/3`.

# `unpublish_checkpoint`

```elixir
@spec unpublish_checkpoint(t(), String.t()) ::
  {:ok, map()} | {:error, Tinkex.Error.t()}
```

Unpublish a checkpoint (make it private).

# `unpublish_checkpoint_async`

```elixir
@spec unpublish_checkpoint_async(t(), String.t()) :: Task.t()
```

Async variant of `unpublish_checkpoint/2`.

Returns a `Task.t()` that resolves to `{:ok, map()} | {:error, Tinkex.Error.t()}`.

# `unpublish_checkpoint_from_tinker_path`

```elixir
@spec unpublish_checkpoint_from_tinker_path(t(), String.t()) ::
  {:ok, map()} | {:error, Tinkex.Error.t()}
```

Unpublish a checkpoint referenced by a tinker path.

Alias for `unpublish_checkpoint/2` to mirror Python convenience naming.

# `unpublish_checkpoint_from_tinker_path_async`

```elixir
@spec unpublish_checkpoint_from_tinker_path_async(t(), String.t()) :: Task.t()
```

Async variant of `unpublish_checkpoint_from_tinker_path/2`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*