# Getting Started with the API

The Lathe Studio API lets you integrate your CI/CD pipeline, automation framework, and external tools with your test management workflow.

**Base URL**

```
https://app.lathe.studio/api/v1
```

All requests use HTTPS. HTTP requests are rejected.

* * *

## Prerequisites

API access requires a **Pro or Enterprise** plan. Basic plan users can upgrade from **Org Settings → Billing**.

* * *

## Step 1 — Create an API Key

1. Go to **Org Settings → API Keys**  
2. Click **New API Key**  
3. Give the key a descriptive name (e.g. `ci-pipeline-prod`)  
4. Select the scopes the key needs (start with `builds:create` for CI integration, or `testruns:create` for automation frameworks)  
5. Copy the key — it's shown **once** and cannot be retrieved again

Your key looks like this:

```
pt_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
```

Store it in your CI/CD secrets manager (GitHub Actions Secrets, AWS Secrets Manager, etc.).

* * *

## Step 2 — Make Your First Request

Here's a complete example of registering a build from your CI pipeline:

```bash
curl -X POST https://app.lathe.studio/api/v1/builds \
  -H "Authorization: Bearer pt_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "v2.4.1",
    "build_number": "1042",
    "commit_sha": "a1b2c3d4e5f6789012345678901234567890abcd",
    "branch": "main"
  }'
```

**Successful response (202 — queued for release assignment):**

```json
{
  "id": "bld_01HABC",
  "name": "v2.4.1",
  "status": "planned",
  "source": "api",
  "queue_position": 1,
  "message": "Build queued for release assignment."
}
```

The build now appears in the **Build Queue** in the Lathe Studio UI, ready to be assigned to a release.

If you include a `release_id`, the build is created immediately with a `201` response.

* * *

## Response Structure

All successful responses return JSON. Collection endpoints wrap results in a `data` array with a `pagination` object:

```json
{
  "data": [ ... ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}
```

Single-resource endpoints return the object directly.

* * *

## Error Structure

All errors use the same envelope:

```json
{
  "error": "invalid_request",
  "message": "The 'name' field is required.",
  "details": {
    "field": "name"
  }
}
```

See Error Reference for the full list of error codes.

* * *

## GitHub Actions Example

Add this step to your workflow after a successful deployment:

```yaml
- name: Register build with Lathe Studio
  run: |
    curl -X POST https://app.lathe.studio/api/v1/builds \
      -H "Authorization: Bearer ${{ secrets.LATHE_STUDIO_API_KEY }}" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "${{ github.ref_name }}",
        "build_number": "${{ github.run_number }}",
        "commit_sha": "${{ github.sha }}",
        "branch": "${{ github.ref_name }}",
        "repo_url": "${{ github.server_url }}/${{ github.repository }}"
      }'
```

* * *

## What's Next

- Authentication — key scopes, rotation, project-scoped keys
- Rate Limits — tier-based limits and retry guidance
- Interactive Explorer — try every endpoint live with Redoc