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

# Overview

> Official client libraries for the Arga API

Arga provides official SDKs for Python and TypeScript. Both now expose the newer run-model resources for sandboxes, twin runs, saved tests, and ad hoc test runs, while still keeping the older `runs` helpers for legacy validation flows.

<CardGroup cols={2}>
  <Card title="Python" icon="python" href="/sdks/python">
    Sync and async support. Works with any Python 3.10+ project.
  </Card>

  <Card title="TypeScript" icon="js" href="/sdks/typescript">
    Zero dependencies. Uses native fetch (Node 18+).
  </Card>
</CardGroup>

## What the SDKs cover

Both SDKs wrap the same core namespaces:

| Namespace        | What it does                                                                                       |
| ---------------- | -------------------------------------------------------------------------------------------------- |
| **Sandbox runs** | Deploy app code plus selected twins. Inspect sandbox URLs and logs.                                |
| **Twin runs**    | Provision standalone digital twin environments, extend TTL, lock public access, or tear them down. |
| **Tests**        | Create, list, fetch, and run saved browser tests.                                                  |
| **Test runs**    | Start ad hoc browser runs, rerun them, and poll for completion.                                    |
| **Twins**        | Legacy twin quickstart helpers on the older `/validate/twins/...` routes.                          |
| **Scenarios**    | Create reusable twin seed configurations and reuse them across runs.                               |
| **Runs**         | Legacy validation-run helpers kept for older `/validate/...` workflows.                            |

<Warning>
  Current SDK packages still include legacy agent-run helpers, but those helpers target the removed `/validate/agent-run` endpoint. Prefer `sandbox_runs` / `sandboxRuns`, `twin_runs` / `twinRuns`, `tests`, and `test_runs` / `testRuns` for new integrations.
</Warning>

## Authentication

All SDK methods require an API key. Get one by running:

```bash theme={null}
arga login
```

The CLI stores your key locally. To use it in the SDK, copy the key from your Arga dashboard or pass it directly:

<CodeGroup>
  ```python Python theme={null}
  from arga_sdk import Arga

  client = Arga(api_key="arga_sk_...")
  ```

  ```typescript TypeScript theme={null}
  import { Arga } from 'arga-sdk';

  const client = new Arga({ apiKey: 'arga_sk_...' });
  ```
</CodeGroup>

## Example projects

Both SDK repositories include reference tests and package-level examples for the current supported workflows — release gating, scenario creation, seeded twin provisioning, and standalone twin provisioning.

| Example                             | What it does                                                                                             |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Validate staging release**        | Run browser validation against staging and exit non-zero if it fails — drop it into CI to gate releases. |
| **Create checkout scenario**        | Build a reusable scenario with seed data and tags so your team can replay the same flow across runs.     |
| **Provision twins from a scenario** | Start a seeded twin session from a saved scenario and print the resulting `base_url`s.                   |
| **Provision checkout twins**        | Spin up disposable service twins (e.g. Stripe), wait until ready, and print the URLs and env vars.       |

<CardGroup cols={2}>
  <Card title="Python examples" icon="python" href="https://github.com/ArgaLabs/arga-python-sdk/tree/main/examples">
    `uv run python examples/validate_staging_release.py`
  </Card>

  <Card title="TypeScript examples" icon="js" href="https://github.com/ArgaLabs/arga-typescript-sdk/tree/main/examples">
    `npx tsx examples/validate_staging_release.ts`
  </Card>
</CardGroup>

## Base URL

Both SDKs default to `https://app.argalabs.com`. Override this if you're targeting a different environment:

<CodeGroup>
  ```python Python theme={null}
  client = Arga(api_key="...", base_url="https://your-instance.example.com")
  ```

  ```typescript TypeScript theme={null}
  const client = new Arga({ apiKey: '...', baseUrl: 'https://your-instance.example.com' });
  ```
</CodeGroup>