> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vambe.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Update metadata of a ticket

> Updates metadata of the active ticket, or the latest closed ticket if allow_closed_ticket is true.

## Overview

Updates metadata fields for a ticket. Metadata is a set of key-value string pairs that you can attach to a ticket for custom tracking (e.g. order IDs, priorities, tags).

By default, this endpoint targets the contact's **active ticket**. Set `allow_closed_ticket` to `true` to fall back to the **latest closed ticket** when no active ticket exists.

## Authentication

Include your API key in the request headers:

```bash theme={null}
x-api-key: your_api_key_here
```

## Request Body

| Field                 | Type            | Required     | Description                                                                                          |
| --------------------- | --------------- | ------------ | ---------------------------------------------------------------------------------------------------- |
| `ticket_id`           | `string` (UUID) | One of three | Directly target a ticket by its ID.                                                                  |
| `ai_contact_id`       | `string` (UUID) | One of three | Find the ticket through a contact ID.                                                                |
| `contact_number`      | `string`        | One of three | Find the ticket through a contact phone number (e.g. `+56912345678`).                                |
| `metadata`            | `object`        | Yes          | Key-value pairs (`string: string`) to set on the ticket. Merges with existing metadata.              |
| `allow_closed_ticket` | `boolean`       | No           | When `true`, falls back to the latest closed ticket if no active ticket exists. Defaults to `false`. |

> You must provide **exactly one** identifier: `ticket_id`, `ai_contact_id`, or `contact_number`.

## Example Requests

### By contact number

```bash theme={null}
curl --request POST \
  'https://api.vambe.me/api/public/ticket/metadata' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: your_api_key_here' \
  --data-raw '{
    "contact_number": "+56912345678",
    "metadata": {
      "order_id": "ORD-12345",
      "priority": "high"
    }
  }'
```

### By AI contact ID (with closed ticket fallback)

```bash theme={null}
curl --request POST \
  'https://api.vambe.me/api/public/ticket/metadata' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: your_api_key_here' \
  --data-raw '{
    "ai_contact_id": "df980fc8-b6db-4820-bf22-2969482d106d",
    "allow_closed_ticket": true,
    "metadata": {
      "order_id": "ORD-12345",
      "refund_reason": "damaged_product"
    }
  }'
```

### By ticket ID

```bash theme={null}
curl --request POST \
  'https://api.vambe.me/api/public/ticket/metadata' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: your_api_key_here' \
  --data-raw '{
    "ticket_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "metadata": {
      "status": "escalated"
    }
  }'
```

## Responses

### 200 - Success

```json theme={null}
{
  "status": "ok"
}
```

### 400 - Bad Request

Returned when no identifier is provided or the request body is invalid.

```json theme={null}
{
  "statusCode": 400,
  "message": "You must provide ticket_id, ai_contact_id, or contact_number"
}
```

### 404 - Not Found

Returned when the contact or ticket cannot be found.

```json theme={null}
{
  "statusCode": 404,
  "message": "Active ticket not found for contact"
}
```


## OpenAPI

````yaml post /api/public/ticket/metadata
openapi: 3.0.0
info:
  title: Vambe AI API
  description: Vambe AI documentation
  version: '1.0'
  contact: {}
servers:
  - url: https://api.vambe.me
    description: Production Server
security: []
tags:
  - name: Vambe AI
    description: ''
paths:
  /api/public/ticket/metadata:
    post:
      tags:
        - Ticket
      summary: Update metadata of a ticket
      description: >-
        Updates metadata of the active ticket, or the latest closed ticket if
        allow_closed_ticket is true.
      operationId: UpdateTicketPublicController_updateTicketMetadata
      parameters:
        - name: x-api-key
          in: header
          description: API key needed to authorize the request
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ticket_id:
                  format: uuid
                  type: string
                ai_contact_id:
                  format: uuid
                  type: string
                contact_number:
                  type: string
                allow_closed_ticket:
                  type: boolean
                metadata:
                  type: object
                  additionalProperties:
                    type: string
              required:
                - metadata
              example:
                contact_number: '+56912345678'
                allow_closed_ticket: true
                metadata:
                  order_id: ORD-12345
                  priority: high
      responses:
        '200':
          description: Ticket metadata updated successfully
        '400':
          description: >-
            Invalid request - provide ticket_id, ai_contact_id, or
            contact_number
        '404':
          description: Ticket not found

````