# Add a note to a ticket (/api-reference/tickets/addTicketNote)

## POST /api/v1/tickets/{ticket_id}/activities

Operation ID: `addTicketNote`
Add a note to a ticket
A note your team sees on the ticket; the customer does not. Optionally moves the ticket's status.

### Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `ticket_id` | path | yes | Ticket id. |
| `Idempotency-Key` | header | no | Any unique string up to 255 characters. Retrying with the same key and body within 24 hours returns the first result instead of acting twice. |

### Request body

`application/json` (required)

```json
{
  "description": "A private team note, never sent to the customer; a note may be just attachments.",
  "properties": {
    "attachmentIds": {
      "description": "Files already uploaded to the ticket (console only).",
      "items": {
        "type": "string"
      },
      "maxItems": 5,
      "title": "Attachmentids",
      "type": "array"
    },
    "note": {
      "default": "",
      "description": "Note text, visible to your team only.",
      "maxLength": 8000,
      "title": "Note",
      "type": "string"
    },
    "status": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Also move the ticket to this status: `open`, `in_progress`, `waiting_on_customer`, `resolved` or `closed`.",
      "title": "Status"
    },
    "version": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "The `version` you last read; if the ticket changed since, the request fails with 409. Leave out to skip.",
      "title": "Version"
    }
  },
  "title": "TicketActivityBody",
  "type": "object"
}
```

Example:

```json
{
  "note": "Courier confirmed the parcel is at the local hub; asked them to redeliver tomorrow.",
  "status": "waiting_on_customer",
  "version": 2
}
```

### Responses

#### 200 OK

Example (example):

```json
{
  "activities": [
    {
      "activityType": "status_change",
      "actorName": "Priya Nair",
      "actorUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f",
      "createdAt": "2026-01-15T11:20:00+00:00",
      "id": "5f6a7b8c-9d0e-4f1a-9b2c-4d5e6f7a8b9d",
      "payload": {
        "from": "in_progress",
        "source": "console",
        "to": "waiting_on_customer"
      },
      "ticketId": "5f0c9a3e-2b7d-4c61-9e84-1d6a7b3c2f90"
    },
    {
      "activityType": "comment",
      "actorName": "Priya Nair",
      "actorUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f",
      "createdAt": "2026-01-15T11:20:00+00:00",
      "id": "3d4e5f6a-7b8c-4d9e-9f0a-2b3c4d5e6f7a",
      "payload": {
        "note": "Courier confirmed the parcel is at the local hub; asked them to redeliver tomorrow."
      },
      "ticketId": "5f0c9a3e-2b7d-4c61-9e84-1d6a7b3c2f90"
    }
  ],
  "changed": [
    "status",
    "activities"
  ],
  "success": true,
  "ticket": {
    "activityCount": 5,
    "assignedToUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f",
    "assigneeEmail": "priya@example.com",
    "assigneeName": "Priya Nair",
    "assigneeNames": [
      "Priya Nair"
    ],
    "assignees": [
      {
        "assignedAt": "2026-01-15T09:30:02+00:00",
        "email": "priya@example.com",
        "name": "Priya Nair",
        "userId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f"
      }
    ],
    "canEdit": true,
    "canManageAssignees": true,
    "canReopenClosed": false,
    "categoryId": "3b9f1d7e-6c2a-4e85-a0d4-7f1e2c3b4a56",
    "categoryName": "Delivery",
    "createdAt": "2026-01-15T09:30:00+00:00",
    "createdByUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f",
    "description": "Customer says the parcel was marked delivered but never arrived.",
    "dueAt": "2026-01-16T09:30:00+00:00",
    "id": "5f0c9a3e-2b7d-4c61-9e84-1d6a7b3c2f90",
    "leadId": "a41e7c2d-8f35-4b09-b6d2-93c0e5f1a7b8",
    "leadName": "Asha Verma",
    "leadPhone": "+919812345678",
    "merchantId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
    "overdue": false,
    "priority": "high",
    "ref": "T-5F0C9A3E",
    "sla": {
      "firstResponse": {
        "dueAt": "2026-01-15T13:30:00+00:00",
        "state": "ok",
        "warnAt": "2026-01-15T12:30:00+00:00"
      },
      "paused": false,
      "resolution": {
        "dueAt": "2026-01-16T09:30:00+00:00",
        "state": "ok",
        "warnAt": "2026-01-16T05:30:00+00:00"
      }
    },
    "source": "manual",
    "status": "waiting_on_customer",
    "subject": "Order #1042 not delivered",
    "tags": [
      "order-1042"
    ],
    "teamId": "e7a1c3d5-9b2f-4d68-8a0c-2e4f6a8b0c1d",
    "teamName": "Customer care",
    "type": "support",
    "updatedAt": "2026-01-15T11:20:00+00:00",
    "version": 3
  }
}
```

#### 400 Bad request: `bad_request`.

Example (The request could not be processed.):

```json
{
  "detail": "The request could not be processed.",
  "error": {
    "code": "bad_request",
    "docUrl": "https://docs.callmitra.ai/errors/bad_request",
    "message": "The request could not be processed.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`.

Example (The API key has expired.):

```json
{
  "detail": "The API key has expired.",
  "error": {
    "code": "api_key_expired",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_expired",
    "message": "The API key has expired.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (The API key is invalid or has been revoked.):

```json
{
  "detail": "The API key is invalid or has been revoked.",
  "error": {
    "code": "invalid_api_key",
    "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key",
    "message": "The API key is invalid or has been revoked.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (Authentication required.):

```json
{
  "detail": "Authentication required.",
  "error": {
    "code": "unauthenticated",
    "docUrl": "https://docs.callmitra.ai/errors/unauthenticated",
    "message": "Authentication required.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

#### 403 Forbidden: `api_key_scope_denied`, `permission_denied`, `ticket_edit_forbidden`, `ticket_reopen_forbidden`.

Example (The API key does not have the scope required for this request.):

```json
{
  "detail": "The API key does not have the scope required for this request.",
  "error": {
    "code": "api_key_scope_denied",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied",
    "message": "The API key does not have the scope required for this request.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

Example (You do not have permission to perform this action.):

```json
{
  "detail": "You do not have permission to perform this action.",
  "error": {
    "code": "permission_denied",
    "docUrl": "https://docs.callmitra.ai/errors/permission_denied",
    "message": "You do not have permission to perform this action.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

Example (You can only update tickets assigned to you or unassigned.):

```json
{
  "detail": "You can only update tickets assigned to you or unassigned.",
  "error": {
    "code": "ticket_edit_forbidden",
    "docUrl": "https://docs.callmitra.ai/errors/ticket_edit_forbidden",
    "message": "You can only update tickets assigned to you or unassigned.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

Example (Only a manager can reopen a closed ticket.):

```json
{
  "detail": "Only a manager can reopen a closed ticket.",
  "error": {
    "code": "ticket_reopen_forbidden",
    "docUrl": "https://docs.callmitra.ai/errors/ticket_reopen_forbidden",
    "message": "Only a manager can reopen a closed ticket.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

#### 404 Not found: `resource_not_found`.

Example (The requested resource was not found.):

```json
{
  "detail": "The requested resource was not found.",
  "error": {
    "code": "resource_not_found",
    "docUrl": "https://docs.callmitra.ai/errors/resource_not_found",
    "message": "The requested resource was not found.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "not_found_error"
  }
}
```

#### 409 Conflict: `idempotency_key_reused`, `idempotency_request_in_progress`, `ticket_attachment_unavailable`, `ticket_merged`, `ticket_version_conflict`.

Example (This Idempotency-Key was already used with a different request body.):

```json
{
  "detail": "This Idempotency-Key was already used with a different request body.",
  "error": {
    "code": "idempotency_key_reused",
    "docUrl": "https://docs.callmitra.ai/errors/idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request body.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "idempotency_error"
  }
}
```

Example (A request with this Idempotency-Key is still being processed.):

```json
{
  "detail": "A request with this Idempotency-Key is still being processed.",
  "error": {
    "code": "idempotency_request_in_progress",
    "docUrl": "https://docs.callmitra.ai/errors/idempotency_request_in_progress",
    "message": "A request with this Idempotency-Key is still being processed.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "idempotency_error"
  }
}
```

Example (An attachment was already sent or removed.):

```json
{
  "detail": "An attachment was already sent or removed.",
  "error": {
    "code": "ticket_attachment_unavailable",
    "docUrl": "https://docs.callmitra.ai/errors/ticket_attachment_unavailable",
    "message": "An attachment was already sent or removed.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "conflict_error"
  }
}
```

Example (The ticket was merged into another ticket.):

```json
{
  "detail": "The ticket was merged into another ticket.",
  "error": {
    "code": "ticket_merged",
    "docUrl": "https://docs.callmitra.ai/errors/ticket_merged",
    "message": "The ticket was merged into another ticket.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "conflict_error"
  }
}
```

Example (The ticket was changed since you read it.):

```json
{
  "detail": "The ticket was changed since you read it.",
  "error": {
    "code": "ticket_version_conflict",
    "docUrl": "https://docs.callmitra.ai/errors/ticket_version_conflict",
    "message": "The ticket was changed since you read it.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "conflict_error"
  }
}
```

#### 422 Invalid parameters: `parameter_invalid`.

Example (One or more parameters are invalid.):

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "phone"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ],
  "error": {
    "code": "parameter_invalid",
    "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid",
    "message": "One or more parameters are invalid.",
    "param": "phone",
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 429 Too many requests: `rate_limit_exceeded`.

Example (Too many requests. Slow down and retry later.):

```json
{
  "detail": "Too many requests. Slow down and retry later.",
  "error": {
    "code": "rate_limit_exceeded",
    "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded",
    "message": "Too many requests. Slow down and retry later.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "rate_limit_error"
  }
}
```

#### 500 Server error: `internal_error`.

Example (Something went wrong on our side.):

```json
{
  "detail": "Something went wrong on our side.",
  "error": {
    "code": "internal_error",
    "docUrl": "https://docs.callmitra.ai/errors/internal_error",
    "message": "Something went wrong on our side.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "api_error"
  }
}
```

### Error codes

- [`bad_request`](/errors/bad_request)
- [`api_key_expired`](/errors/api_key_expired)
- [`invalid_api_key`](/errors/invalid_api_key)
- [`unauthenticated`](/errors/unauthenticated)
- [`api_key_scope_denied`](/errors/api_key_scope_denied)
- [`permission_denied`](/errors/permission_denied)
- [`ticket_edit_forbidden`](/errors/ticket_edit_forbidden)
- [`ticket_reopen_forbidden`](/errors/ticket_reopen_forbidden)
- [`resource_not_found`](/errors/resource_not_found)
- [`idempotency_key_reused`](/errors/idempotency_key_reused)
- [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress)
- [`ticket_attachment_unavailable`](/errors/ticket_attachment_unavailable)
- [`ticket_merged`](/errors/ticket_merged)
- [`ticket_version_conflict`](/errors/ticket_version_conflict)
- [`parameter_invalid`](/errors/parameter_invalid)
- [`rate_limit_exceeded`](/errors/rate_limit_exceeded)
- [`internal_error`](/errors/internal_error)
