All Docs
Getting Started with the API

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:

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):

{
  "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:

{
  "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:

{
  "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:

- 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#

← All DocsSettings →