# Clanker instructions

Clanker instructions that no status holds: the defaults a clanker's new ticket gets, and how to write test cases, specs, a Fixture API and test CI. A workspace and each team can set their own; a team's replace the workspace's, which replace Clanker Ship's defaults. Each status keeps its own instructions for its document and work; see Ticket statuses.

## The ClankerInstructions object

The instructions of one kind that a team's clankers follow, and where they come from.

### Attributes

- `kind` (string, one of: `ticket`, `test-cases`, `test-code`, `fixtures`, `test-ci`, required): What the instructions shape: `ticket` for the defaults a clanker's new ticket gets, `test-cases` for test cases, `test-code` for specs, `fixtures` for a product's Fixture API and `test-ci` for the CI that runs tests. Each status keeps its own instructions for its document and work.
- `source` (string, one of: `team`, `workspace`, `default`, required): Where these come from: the team's own (team), the workspace's (workspace) or Clanker Ship's defaults (default).
- `team` (nullable object, required): The team asked about, or null for the workspace's instructions.
  - `id` (string, required): Unique ID of the team.
  - `key` (string, required): 2 to 5 capital letters that start the team's ticket IDs, such as WEB.
  - `name` (string, required): The team's display name.
- `templates` (array of objects, required): One template for every ticket, and at most one more per tag; empty for ticket instructions.
  - `tag` (nullable string, required): The tag whose tickets start from this template, or null for the template every other ticket uses.
  - `body` (string, required): The Markdown a test case, spec or setup starts from.
- `guidance` (string, required): How the clanker should write, in Markdown; empty for ticket instructions.
- `defaults` (nullable object, required): What new tickets from clankers get; null for the test kinds.
  - `status` (nullable string, required): The name of the status new tickets get, or null for the team's default status.
  - `tags` (array of strings, required): The names of the tags new tickets get.
  - `owner` (string, one of: `creator`, `none`, required): `creator` makes the person the creating clanker works for the ticket's owner; `none` leaves the ticket without one.
  - `clankers` (string, one of: `creator`, `none`, required): `creator` makes the clanker that creates the ticket its one clanker; `none` leaves it without clankers.
- `updatedAt` (nullable string, required): When these were last set, as an ISO 8601 timestamp; null for Clanker Ship's defaults.
- `updatedBy` (nullable object, required): Who last set these; null for Clanker Ship's defaults or when an account API key set them.
  - `person` (nullable object, required): The person who acted, or the person the clanker works for; null for an account API key.
    - `id` (string, required): The person's user ID.
    - `name` (string, required): The person's display name.
    - `email` (string, required): The person's email address.
    - `image` (nullable string, required): The URL of the person's account photo, or null when they have none.
  - `clanker` (nullable object, required): The clanker that acted for the person, or null when the person acted directly. See [the Clanker object](https://docs.clankership.com/api/clankers/object.md).
    - `id` (string, required): Unique ID of the clanker.
    - `name` (string, required): The clanker, such as Codex.
    - `person` (object, required): A person in the workspace.
      - `id` (string, required): The person's user ID.
      - `name` (string, required): The person's display name.
      - `email` (string, required): The person's email address.
      - `image` (nullable string, required): The URL of the person's account photo, or null when they have none.

### Example

```json
{
  "kind": "ticket",
  "source": "team",
  "team": {
    "id": "Tm6PzN3kWq1J",
    "key": "WEB",
    "name": "Web"
  },
  "templates": [],
  "guidance": "",
  "defaults": {
    "status": "Plan",
    "tags": [],
    "owner": "creator",
    "clankers": "creator"
  },
  "updatedAt": "2026-10-14T09:05:12.000Z",
  "updatedBy": {
    "person": {
      "id": "Us3NfP8kLq2V",
      "name": "Maya Patel",
      "email": "maya@acme.dev",
      "image": null
    },
    "clanker": null
  }
}
```

## Get clanker instructions

`GET /v1/workspaces/{slug}/clanker-instructions`

Returns the instructions a team's clankers follow: the team's own, else the workspace's, else Clanker Ship's defaults. Without `team`, returns the workspace's or Clanker Ship's. `source` says which.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `kind` (string, one of: `ticket`, `test-cases`, `test-code`, `fixtures`, `test-ci`, in query, required): What the instructions shape: `ticket` for the defaults a clanker's new ticket gets, `test-cases` for test cases, `test-code` for specs, `fixtures` for a product's Fixture API and `test-ci` for the CI that runs tests.
- `team` (string, in query): A team's key, such as WEB. Leave it out for the workspace's instructions.

### Returns

Returns the [ClankerInstructions](https://docs.clankership.com/api/clanker-instructions/object.md) object. The status is 200.

### Request

```bash
curl "https://api.clankership.com/v1/workspaces/{slug}/clanker-instructions?kind=ticket" \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

### Response

```json
{
  "kind": "ticket",
  "source": "team",
  "team": {
    "id": "Tm6PzN3kWq1J",
    "key": "WEB",
    "name": "Web"
  },
  "templates": [],
  "guidance": "",
  "defaults": {
    "status": "Plan",
    "tags": [],
    "owner": "creator",
    "clankers": "creator"
  },
  "updatedAt": "2026-10-14T09:05:12.000Z",
  "updatedBy": {
    "person": {
      "id": "Us3NfP8kLq2V",
      "name": "Maya Patel",
      "email": "maya@acme.dev",
      "image": null
    },
    "clanker": null
  }
}
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.

## Set clanker instructions

`PUT /v1/workspaces/{slug}/clanker-instructions`

Sets the workspace's or a team's own instructions. Fields left out keep their current values, so a team's first change copies what it inherits. Owners and admins set the workspace's, and a team's members also set the team's; viewers cannot. Only ticket instructions take `defaults`.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `kind` (string, one of: `ticket`, `test-cases`, `test-code`, `fixtures`, `test-ci`, required): What the instructions shape: `ticket` for the defaults a clanker's new ticket gets, `test-cases` for test cases, `test-code` for specs, `fixtures` for a product's Fixture API and `test-ci` for the CI that runs tests.
- `team` (nullable string): A team's key, such as WEB. Leave it out for the workspace's instructions.
- `templates` (array of objects): Replaces the templates: exactly one without a tag, and at most one more per tag, up to 20 in all. Not for ticket instructions.
  - `tag` (nullable string, required): The tag whose tickets start from this template, or null for the template every other ticket uses.
  - `body` (string, required): The Markdown a test case, spec or setup starts from.
- `guidance` (string): How the clanker should write, in Markdown, up to 20,000 characters. Not for ticket instructions.
- `defaults` (object): What a ticket a clanker creates gets for each of these fields the clanker leaves out.
  - `status` (nullable string, required): The name of the status new tickets get, or null for the team's default status.
  - `tags` (array of strings, required): The names of the tags new tickets get.
  - `owner` (string, one of: `creator`, `none`, required): `creator` makes the person the creating clanker works for the ticket's owner; `none` leaves the ticket without one.
  - `clankers` (string, one of: `creator`, `none`, required): `creator` makes the clanker that creates the ticket its one clanker; `none` leaves it without clankers.

### Returns

Returns the [ClankerInstructions](https://docs.clankership.com/api/clanker-instructions/object.md) object. The status is 200.

### Request

```bash
curl -X PUT https://api.clankership.com/v1/workspaces/{slug}/clanker-instructions \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "ticket",
    "team": "WEB",
    "defaults": {
      "status": "Plan",
      "tags": [],
      "owner": "creator",
      "clankers": "creator"
    }
  }'
```

### Response

```json
{
  "kind": "ticket",
  "source": "team",
  "team": {
    "id": "Tm6PzN3kWq1J",
    "key": "WEB",
    "name": "Web"
  },
  "templates": [],
  "guidance": "",
  "defaults": {
    "status": "Plan",
    "tags": [],
    "owner": "creator",
    "clankers": "creator"
  },
  "updatedAt": "2026-10-14T09:05:12.000Z",
  "updatedBy": {
    "person": {
      "id": "Us3NfP8kLq2V",
      "name": "Maya Patel",
      "email": "maya@acme.dev",
      "image": null
    },
    "clanker": null
  }
}
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.

## Reset clanker instructions

`DELETE /v1/workspaces/{slug}/clanker-instructions`

Removes the workspace's or a team's own instructions, so it follows what it inherits again, and returns the instructions that now apply. The people who can set the instructions can reset them.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `kind` (string, one of: `ticket`, `test-cases`, `test-code`, `fixtures`, `test-ci`, in query, required): What the instructions shape: `ticket` for the defaults a clanker's new ticket gets, `test-cases` for test cases, `test-code` for specs, `fixtures` for a product's Fixture API and `test-ci` for the CI that runs tests.
- `team` (string, in query): A team's key, such as WEB. Leave it out for the workspace's instructions.

### Returns

Returns the [ClankerInstructions](https://docs.clankership.com/api/clanker-instructions/object.md) object. The status is 200.

### Request

```bash
curl -X DELETE "https://api.clankership.com/v1/workspaces/{slug}/clanker-instructions?kind=ticket" \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

### Response

```json
{
  "kind": "ticket",
  "source": "team",
  "team": {
    "id": "Tm6PzN3kWq1J",
    "key": "WEB",
    "name": "Web"
  },
  "templates": [],
  "guidance": "",
  "defaults": {
    "status": "Plan",
    "tags": [],
    "owner": "creator",
    "clankers": "creator"
  },
  "updatedAt": "2026-10-14T09:05:12.000Z",
  "updatedBy": {
    "person": {
      "id": "Us3NfP8kLq2V",
      "name": "Maya Patel",
      "email": "maya@acme.dev",
      "image": null
    },
    "clanker": null
  }
}
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.