# Tag one of your bot's trades with one of its setups

`PUT https://app.skylit.ai/api/nexus/v1/trades/{id}/playbook`

API: Nexus.

A bot trade takes a setup of your bot's account only (`400 wrong_account` for one of your own). `checks` replaces the trade's answers: send every rule you answered; a rule you leave out is unknown, never "not followed". Tagging again with another setup clears the old setup's answers.

```bash
curl -s -X PUT "https://app.skylit.ai/api/nexus/v1/trades/$TRADE_ID/playbook" \
  -H "Authorization: Bearer $SKYLIT_API_KEY" -H "Content-Type: application/json" \
  -d '{"playbookId":"'$SETUP_ID'","checks":[{"ruleId":"'$RULE_ID'","followed":true}]}'
```

## Authentication

Send your Skylit API key as a bearer token: `Authorization: Bearer <key>`. No other header is accepted.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | The trade id (`tradeId` on GET /v1/trades). Options and stock trades; a futures position is `404 trade_not_found`. |

## Request body

`application/json`

```json
{
  "playbookId": "string",
  "checks": [
    {
      "ruleId": "string",
      "followed": false
    }
  ]
}
```

## Example request

```bash
curl "https://app.skylit.ai/api/nexus/v1/trades/{id}/playbook" \
  -H "Authorization: Bearer $SKYLIT_API_KEY"
```

## Responses

### 200

The tag as saved: `{"tag": {...}}`.

The trade, now tagged.:

```json
{
  "data": {
    "tag": {
      "tradeId": "0254e24b-e6ce-4cc0-b516-b92fdf469153",
      "playbookId": "50873e40-8b0f-4cf6-a031-3da471b99dd6",
      "playbookName": "ORB 5m",
      "createdAt": "2026-11-18T13:57:56.974421-05:00",
      "updatedAt": "2026-11-18T13:57:56.977003-05:00",
      "checks": [
        {
          "ruleId": "bce4ec96-1a98-4dea-8dd4-fd7f19cababa",
          "label": "Breaks the first 5 minute range",
          "followed": true
        },
        {
          "ruleId": "2c727d44-4ba0-4d96-86bd-0b83f44e4474",
          "label": "Volume over the 20 day average",
          "followed": false
        }
      ],
      "rulesFollowed": 1,
      "rulesAnswered": 2
    }
  },
  "meta": {
    "account": "agent"
  }
}
```

### 400

`wrong_account` (a setup of your own on a bot trade), or `bad_request` (no playbookId, an archived setup, a rule answered twice).

### 403

`main_account_web_only`: your own account's setups and tags are changed only on skylit.ai, signed in as yourself.

### 404

`trade_not_found`, `playbook_not_found` or `rule_not_found` (a rule that is not on that setup).
