# Commands

Enrollment and stop results, processing states and queue status.

Base URL: https://api.melioralab.io/v1. Pass the key in the `Authorization: Bearer mel_live_...` header.

Endpoints:

- `GET /v1/commands/{id}`: Get a command

## The Command object

Enrollment or stop command. Completed processing does not confirm sending.

| Field | Type | Description |
|---|---|---|
| `object` | string | Object type, always `command`. |
| `id` | string (uuid) | Identifier for polling this command. |
| `kind` | string | `enroll`: enrollment; `stop`: stopping. Values: `enroll`, `stop`. |
| `state` | string | `accepted`, `running`, `done`, `done_with_unknown`, `failed`. This is the command processing state. Values: `accepted`, `running`, `done`, `done_with_unknown`, `failed`. |
| `workspace_id` | string (uuid) | Original command workspace. |
| `campaign_id` | string (uuid) | Original command campaign. |
| `lead_id` | string (uuid) or null | Stop target lead; `null` for a batch. |
| `created_at` | string (date-time) | Command acceptance time. |
| `finished_at` | string (date-time) or null | Completion time or `null`. |
| `cleanup_pending` | boolean | Stopped work still needs cleanup. Continue polling. |
| `result` | object | Enrollment counters or stop result. |
| `items` | array of object | Lead results in input order. Empty for a stop. |
| `items[].input_index` | integer | Zero-based input index. |
| `items[].lead_id` | string (uuid) or null | Accepted or existing lead; `null` on rejection. |
| `items[].username` | string or null | Normalized username or `null`. |
| `items[].external_id` | string or null | External identifier or `null`. |
| `items[].status` | string | `accepted`: new lead; `existing`: existing and unchanged; `rejected`: refused. Values: `accepted`, `existing`, `rejected`. |
| `items[].reason` | string or null | Rejection or hold reason, or `null`. |
| `items[].warnings` | array of string | `first_message_long` at 700 characters or more. |
| `items[].queue_state` | string | `waiting`, `queued`, `held`, `failed`, `stopped`, `not_required`. Enqueue does not confirm sending. Values: `waiting`, `queued`, `held`, `failed`, `stopped`, `not_required`. |

Example:

```json
{
  "object": "command",
  "id": "bd465c91-d715-4987-ab61-e63a9f01c625",
  "kind": "enroll",
  "state": "accepted",
  "workspace_id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43",
  "campaign_id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14",
  "lead_id": null,
  "created_at": "2026-10-27T09:15:42.000Z",
  "finished_at": null,
  "cleanup_pending": false,
  "result": {
    "accepted": 1,
    "inserted": 1
  },
  "items": [
    {
      "input_index": 0,
      "lead_id": "5a7c3e92-1f4b-4d68-9c2e-7b0a6d4f8e31",
      "username": "example_lead",
      "external_id": "crm-1042",
      "status": "accepted",
      "reason": null,
      "warnings": [],
      "queue_state": "waiting"
    }
  ]
}
```

## The CommandItem object

Intake and enqueue result for one lead.

| Field | Type | Description |
|---|---|---|
| `input_index` | integer | Zero-based input index. |
| `lead_id` | string (uuid) or null | Accepted or existing lead; `null` on rejection. |
| `username` | string or null | Normalized username or `null`. |
| `external_id` | string or null | External identifier or `null`. |
| `status` | string | `accepted`: new lead; `existing`: existing and unchanged; `rejected`: refused. Values: `accepted`, `existing`, `rejected`. |
| `reason` | string or null | Rejection or hold reason, or `null`. |
| `warnings` | array of string | `first_message_long` at 700 characters or more. |
| `queue_state` | string | `waiting`, `queued`, `held`, `failed`, `stopped`, `not_required`. Enqueue does not confirm sending. Values: `waiting`, `queued`, `held`, `failed`, `stopped`, `not_required`. |

Example:

```json
{
  "input_index": 0,
  "lead_id": "5a7c3e92-1f4b-4d68-9c2e-7b0a6d4f8e31",
  "username": "example_lead",
  "external_id": "crm-1042",
  "status": "accepted",
  "reason": null,
  "warnings": [],
  "queue_state": "waiting"
}
```

## The EnrollResult object



| Field | Type | Description |
|---|---|---|
| `accepted` | integer | Number of new leads accepted for enqueue. |
| `inserted` | integer | Number of inserted records, including a possible policy rejection after insertion. Excludes `existing`. |

Example:

```json
{
  "accepted": 1,
  "inserted": 1
}
```

## The StopResult object



| Field | Type | Description |
|---|---|---|
| `automation_state` | string | `stopping`: sending started; `stopped`: no new attempts will start. Values: `stopped`, `stopping`. |
| `send_in_flight` | boolean | An in-flight send may still complete. |
| `unknown_outcome_message_ids` | array of string | Opaque identifiers of unknown outcomes. Do not retry these sends. |

Example:

```json
{
  "automation_state": "stopping",
  "send_in_flight": true,
  "unknown_outcome_message_ids": []
}
```

## Get a command

`GET /v1/commands/{id}`

Requires the command kind permission: `leads:enroll` for enroll, `leads:stop` for stop. Polling does not start sending.

Permission: `leads:enroll | leads:stop`. Request weight: 1.

### Parameters

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes | Command identifier. |

### Response

Returns a `Command` object.

### Endpoint-specific errors

- `scope_required` (403): The key does not permit the operation. A command requires its kind permission.
- `not_found` (404): The object was not found or is outside the key's scope. An unknown path also returns 404.

Common errors: https://docs.melioralab.io/en/md/errors.md

### Example request

```bash
curl https://api.melioralab.io/v1/commands/bd465c91-d715-4987-ab61-e63a9f01c625 \
  -H "Authorization: Bearer $MELIORA_API_KEY"
```

### Example response

```json
{
  "object": "command",
  "id": "bd465c91-d715-4987-ab61-e63a9f01c625",
  "kind": "enroll",
  "state": "accepted",
  "workspace_id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43",
  "campaign_id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14",
  "lead_id": null,
  "created_at": "2026-10-27T09:15:42.000Z",
  "finished_at": null,
  "cleanup_pending": false,
  "result": {
    "accepted": 1,
    "inserted": 1
  },
  "items": [
    {
      "input_index": 0,
      "lead_id": "5a7c3e92-1f4b-4d68-9c2e-7b0a6d4f8e31",
      "username": "example_lead",
      "external_id": "crm-1042",
      "status": "accepted",
      "reason": null,
      "warnings": [],
      "queue_state": "waiting"
    }
  ]
}
```