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

Low-level REST API endpoints for session and checkpoint management.

These functions provide direct access to the Tinker REST API endpoints.
For higher-level operations, use `Tinkex.RestClient`.

# `delete_checkpoint`

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

Delete a checkpoint.

# `delete_checkpoint`

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

Delete a checkpoint by training run and checkpoint ID.

# `get_checkpoint_archive_url`

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

Get the archive download URL for a checkpoint.

The returned URL can be used to download the checkpoint archive.

# `get_checkpoint_archive_url`

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

Get the archive download URL for a checkpoint by IDs.

The returned URL can be used to download the checkpoint archive.

# `get_checkpoint_archive_url`

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

# `get_sampler`

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

Get sampler information.

Retrieves details about a sampler, including the base model and any
custom weights that are loaded.

## Parameters

- `config` - The Tinkex configuration
- `sampler_id` - The sampler ID (sampling_session_id) to query

## Returns

- `{:ok, %GetSamplerResponse{}}` - On success
- `{:error, Tinkex.Error.t()}` - On failure

## Examples

    iex> {:ok, resp} = Rest.get_sampler(config, "session-id:sample:0")
    iex> resp.base_model
    "Qwen/Qwen2.5-7B"

## See Also

- `Tinkex.Types.GetSamplerResponse`

# `get_session`

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

Get session information.

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

# `get_training_run`

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

Get training run information by ID.

## Parameters

- `config` - The Tinkex configuration
- `training_run_id` - The training run ID

## Returns

- `{:ok, map()}` - Training run information on success
- `{:error, Tinkex.Error.t()}` - On failure

# `get_training_run_by_tinker_path`

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

Get training run information by tinker path.

## Parameters

- `config` - The Tinkex configuration
- `tinker_path` - The tinker path to the checkpoint

## Returns

- `{:ok, map()}` - Training run information on success
- `{:error, Tinkex.Error.t()}` - On failure

# `get_weights_info_by_tinker_path`

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

Get checkpoint information from a tinker path.

Retrieves metadata about a checkpoint, including the base model,
whether it uses LoRA, and the LoRA rank.

## Parameters

- `config` - The Tinkex configuration
- `tinker_path` - The tinker path to the checkpoint
  (e.g., `"tinker://run-id/weights/checkpoint-001"`)

## Returns

- `{:ok, %WeightsInfoResponse{}}` - On success
- `{:error, Tinkex.Error.t()}` - On failure

## Examples

    iex> path = "tinker://run-id/weights/checkpoint-001"
    iex> {:ok, resp} = Rest.get_weights_info_by_tinker_path(config, path)
    iex> resp.base_model
    "Qwen/Qwen2.5-7B"
    iex> resp.is_lora
    true
    iex> resp.lora_rank
    32

## Use Cases

### Validating Checkpoint Compatibility

    def validate_checkpoint(config, path, expected_rank) do
      case Rest.get_weights_info_by_tinker_path(config, path) do
        {:ok, %{is_lora: true, lora_rank: ^expected_rank}} ->
          :ok
        {:ok, %{is_lora: true, lora_rank: actual}} ->
          {:error, {:rank_mismatch, expected: expected_rank, actual: actual}}
        {:ok, %{is_lora: false}} ->
          {:error, :not_lora}
        {:error, _} = error ->
          error
      end
    end

## See Also

- `Tinkex.Types.WeightsInfoResponse`

# `list_checkpoints`

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

List checkpoints for a specific training run.

# `list_sessions`

```elixir
@spec list_sessions(Tinkex.Config.t(), integer(), integer(), keyword()) ::
  {:ok, map()} | {:error, Tinkex.Error.t()}
```

List sessions with pagination.

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

# `list_training_runs`

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

List training runs with pagination.

## Parameters

- `config` - The Tinkex configuration
- `limit` - Maximum number of training runs to return (default: 20)
- `offset` - Offset for pagination (default: 0)

## Returns

- `{:ok, map()}` - List of training runs on success
- `{:error, Tinkex.Error.t()}` - On failure

# `list_user_checkpoints`

```elixir
@spec list_user_checkpoints(Tinkex.Config.t(), integer(), integer()) ::
  {:ok, map()} | {: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)

# `publish_checkpoint`

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

Publish a checkpoint to make it public.

# `set_checkpoint_ttl_from_tinker_path`

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

Update checkpoint TTL from a tinker path.

# `unpublish_checkpoint`

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

Unpublish a checkpoint to make it private.

---

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