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.

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",
    "release_id": "22222222-2222-2222-2222-222222222222",
    "build_number": "1042",
    "commit_sha": "a1b2c3d4e5f6789012345678901234567890abcd",
    "branch": "main"
  }'

release_id is required — every build belongs to a release.

Successful response (201 — build created):

{
  "id": "bld_01HABC",
  "name": "v2.4.1",
  "status": "queued",
  "source": "api",
  "message": "Build created successfully"
}

The build is created with status queued and appears under its release in the Lathe Studio UI. Open the build to update its details or change its status to activate it. Pass an explicit "status" (queued, planned, active, or released) in the request body to override the default.

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 →