# Quickstart

Create an API key, make your first call, and record what runs where.

This walkthrough takes about five minutes. You create an API key on the website, check who it acts
for, then describe a product, an environment and the deployment that joins them. The examples use
the Acme workspace (slug `acme`) and its `storefront` product.

## Before you begin

Sign up at [clankertest.com](https://clankertest.com) with Google or an email address. The website
asks you to create a workspace; its slug, such as `acme`, names it in every API path. You need the
member, admin or owner role in the workspace to create products and deployments.

## Create an API key

1. On the website, open **Settings › Security**.
2. Under **API keys**, choose **Create API key** and name it, such as `Quickstart`.
3. Copy the key. It starts with `ctk_` and is shown only once.

Keep it in an environment variable for the rest of this page:

```bash
export CLANKER_API_KEY="ctk_…"
```

A user API key acts as you, with your role in each workspace. For CI, create an account API key
instead; see [Authentication](https://docs.qa.clankership.net/api/authentication.md).

## Make your first call

[Get your profile](https://docs.qa.clankership.net/api/profile/get.md) returns the user the key acts for:

```bash
curl https://api.clankertest.com/v1/me \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

```json
{
  "id": "Us3NfP8kLq2V",
  "name": "Maya Patel",
  "email": "maya@acme.dev",
  "image": "https://images.clankertest.com/users/Us3NfP8kLq2V.webp"
}
```

[List workspaces](https://docs.qa.clankership.net/api/workspaces/list.md) shows each workspace you belong to, with your role:

```bash
curl https://api.clankertest.com/v1/workspaces \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

```json
[
  {
    "id": "Wk7Qm2RtXa9L",
    "name": "Acme",
    "slug": "acme",
    "iconUrl": null,
    "role": "owner"
  }
]
```

## Create an environment

An environment is a place products run. Its class, `production` or `non-production`, is chosen once
and never changes. [Create an environment](https://docs.qa.clankership.net/api/environments/create.md) named Staging:

```bash
curl https://api.clankertest.com/v1/workspaces/acme/environments \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "slug": "staging", "name": "Staging", "class": "non-production" }'
```

The response is the new environment, with status `201 Created`.

## Create a product

A product is a piece of software the workspace tests. [Create a product](https://docs.qa.clankership.net/api/products/create.md) for
the storefront website, with the repository its code lives in:

```bash
curl https://api.clankertest.com/v1/workspaces/acme/products \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "storefront",
    "name": "Storefront",
    "type": "website",
    "repository": "acme/storefront"
  }'
```

## Record a deployment

A deployment says that one product runs in one environment: where it answers and which build is
there. Website and API products need a `baseUrl`. [Create a deployment](https://docs.qa.clankership.net/api/deployments/create.md):

```bash
curl https://api.clankertest.com/v1/workspaces/acme/deployments \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "storefront",
    "environment": "staging",
    "baseUrl": "https://staging.acme.dev",
    "version": "9f2c41e"
  }'
```

```json
{
  "id": "Dp3FkR8wNv2T",
  "product": {
    "id": "Pr4GtY9sLm3B",
    "slug": "storefront",
    "name": "Storefront",
    "type": "website",
    "archived": false
  },
  "environment": {
    "id": "En8RqZ2vKp5D",
    "slug": "staging",
    "name": "Staging",
    "class": "non-production",
    "emoji": null,
    "archived": false
  },
  "baseUrl": "https://staging.acme.dev",
  "fixtureUrl": null,
  "version": "9f2c41e",
  "versionUpdatedAt": "2026-10-14T09:05:12.000Z",
  "active": true,
  "createdAt": "2026-10-14T09:05:12.000Z",
  "updatedAt": "2026-10-14T09:05:12.000Z"
}
```

After each deploy, send the new version with [Update a deployment](https://docs.qa.clankership.net/api/deployments/update.md). Only
the fields you send change, and the server sets `versionUpdatedAt`:

```bash
curl -X PATCH https://api.clankertest.com/v1/workspaces/acme/deployments/storefront/staging \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "version": "4b7e0d2" }'
```

> [!TIP]
> The [`clanker` CLI](https://docs.qa.clankership.net/get-started/concepts/secrets-vault.md) runs the same calls:
> `clanker deployment update storefront staging --deployed-version 4b7e0d2 --workspace acme`.

## Next steps

- [Connect your agent](https://docs.qa.clankership.net/get-started/connect-your-agent.md) so it can read and change tickets.
- [Publish test runs from CI](https://docs.qa.clankership.net/get-started/examples/publish-test-runs-from-ci.md) against this
  deployment.
- [Record a deployment from CI](https://docs.qa.clankership.net/get-started/examples/record-a-deployment.md) on every deploy.
- Read how [errors](https://docs.qa.clankership.net/api/errors.md) look before you script against the API.