VitrinaAPI

Inbox views

Saved inbox filters, team-wide or personal, by conversation attributes; a team view can take its conversations out of «Esperando respuesta».

Beta
This may change at any time, with a changelog entry and a notice to recent callers — see versioning.

Download the full API pública projection: openapi.json.

Reply and resolve tickets explains this resource in prose, with runnable examples.

MethodPathWhat it does
GET/inbox-viewsList the inbox views you see, with their counts
POST/inbox-viewsCreate an inbox view
DELETE/inbox-views/{id}Delete an inbox view
GET/inbox-views/{id}Fetch one inbox view
PATCH/inbox-views/{id}Update an inbox view
GET/inbox-views/attribute-keysConversation-attribute keys and their common values
POST/inbox-views/reorderReorder inbox views

GET /inbox-views

List the inbox views you see, with their counts

The workspace views (position order), then your personal views. A view: \{ id, name, scope: workspace|personal, owner_user_id, filters, exclude_from_waiting, position, created_by, created_at, updated_at, editable \} — editable says whether the caller may change it.

Each view carries count — exactly the total of GET /conversations?viewId=<id> for you (your row visibility applies) — and waiting_count, how many of its matches have a customer waiting on a human (the sidebar badge of a view with exclude_from_waiting). counts=false skips both.

ParameterInTypeRequiredConstraints
countsqueryboolean | nullno
curl https://api.vitrinadev.com/api/v1/inbox-views \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": [
    {
      "id": "6a1f0c7e-3b8d-4e52-9a51-0c2d7b1e9f44",
      "name": "Piden 18 Pro Max",
      "scope": "workspace",
      "owner_user_id": null,
      "filters": {
        "active": true,
        "attributes": [
          {
            "key": "*",
            "op": "contains",
            "value": "18 pro max"
          }
        ]
      },
      "exclude_from_waiting": true,
      "position": 0,
      "created_by": "0b9e2f4a-8c1d-4f37-b6a2-5d3e7c9a1b20",
      "created_at": "2026-11-04T12:00:00.000Z",
      "updated_at": "2026-11-04T12:00:00.000Z",
      "editable": true,
      "count": 21,
      "waiting_count": 15
    }
  ]
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /inbox-views

Create an inbox view

scope: personal (the default) is yours alone; scope: workspace is the whole team’s and needs routing:write (a workspace admin). filters takes the InboxViewFilters subset of GET /conversations filters and needs at least one criterion besides waiting. An attribute condition \{ key, op, value \} compares the value case- and accent-insensitively; key: "*" matches it under any attribute key (one view for modelo_buscado and handoff.reason alike). exclude_from_waiting: true («Sacar de Esperando respuesta») is refused (400) on a personal view; on a workspace view it never takes out an urgent (handoff_urgent) thread. A name already used in the same scope (case-insensitive) is a 409. At most 50 views per scope. Answers 201 with the view.

Body

FieldTypeRequiredConstraints
namestringyesmín. 1, máx. 80
scopeworkspace \personal—
filtersInboxViewFiltersyes
exclude_from_waitingboolean—por defecto false
curl -X POST https://api.vitrinadev.com/api/v1/inbox-views \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Piden 18 Pro Max",
    "scope": "workspace",
    "filters": {
      "active": true,
      "attributes": [
        {
          "key": "*",
          "op": "contains",
          "value": "18 pro max"
        }
      ]
    },
    "exclude_from_waiting": true
  }'

Example response (201)

{
  "data": {
    "id": "6a1f0c7e-3b8d-4e52-9a51-0c2d7b1e9f44",
    "name": "Piden 18 Pro Max",
    "scope": "workspace",
    "owner_user_id": null,
    "filters": {
      "active": true,
      "attributes": [
        {
          "key": "*",
          "op": "contains",
          "value": "18 pro max"
        }
      ]
    },
    "exclude_from_waiting": true,
    "position": 0,
    "created_by": "0b9e2f4a-8c1d-4f37-b6a2-5d3e7c9a1b20",
    "created_at": "2026-11-04T12:00:00.000Z",
    "updated_at": "2026-11-04T12:00:00.000Z",
    "editable": true,
    "count": 21,
    "waiting_count": 15
  }
}

Answers: 201 · 400 · 401 · 403 · 404 · 409 · 429

DELETE /inbox-views/{id}

Delete an inbox view

Deletes the view (never a conversation). A view with exclude_from_waiting puts its matches back in «Esperando respuesta». Answers 204.

ParameterInTypeRequiredConstraints
idpathuuidyes
curl -X DELETE https://api.vitrinadev.com/api/v1/inbox-views/<id> \
  -H "Authorization: Bearer $VITRINA_KEY"

Answers: 204 · 400 · 401 · 403 · 404 · 409 · 429

GET /inbox-views/{id}

Fetch one inbox view

A view: \{ id, name, scope: workspace|personal, owner_user_id, filters, exclude_from_waiting, position, created_by, created_at, updated_at, editable \} — editable says whether the caller may change it. Another member’s personal view is a 404.

ParameterInTypeRequiredConstraints
idpathuuidyes
curl https://api.vitrinadev.com/api/v1/inbox-views/<id> \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": {
    "id": "6a1f0c7e-3b8d-4e52-9a51-0c2d7b1e9f44",
    "name": "Piden 18 Pro Max",
    "scope": "workspace",
    "owner_user_id": null,
    "filters": {
      "active": true,
      "attributes": [
        {
          "key": "*",
          "op": "contains",
          "value": "18 pro max"
        }
      ]
    },
    "exclude_from_waiting": true,
    "position": 0,
    "created_by": "0b9e2f4a-8c1d-4f37-b6a2-5d3e7c9a1b20",
    "created_at": "2026-11-04T12:00:00.000Z",
    "updated_at": "2026-11-04T12:00:00.000Z",
    "editable": true,
    "count": 21,
    "waiting_count": 15
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

PATCH /inbox-views/{id}

Update an inbox view

Any of name, filters (replaced whole), exclude_from_waiting, position. Same rules as create; the scope cannot change. Turning exclude_from_waiting off puts the matches back in «Esperando respuesta» on the next read.

ParameterInTypeRequiredConstraints
idpathuuidyes

Body

FieldTypeRequiredConstraints
namestring—mín. 1, máx. 80
filtersInboxViewFilters—
exclude_from_waitingboolean—
positioninteger—≥ 0, ≤ 10000
curl -X PATCH https://api.vitrinadev.com/api/v1/inbox-views/<id> \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Piden 18 Pro Max (sin respuesta)",
    "exclude_from_waiting": false
  }'

Example response (200)

{
  "data": {
    "id": "6a1f0c7e-3b8d-4e52-9a51-0c2d7b1e9f44",
    "name": "Piden 18 Pro Max",
    "scope": "workspace",
    "owner_user_id": null,
    "filters": {
      "active": true,
      "attributes": [
        {
          "key": "*",
          "op": "contains",
          "value": "18 pro max"
        }
      ]
    },
    "exclude_from_waiting": true,
    "position": 0,
    "created_by": "0b9e2f4a-8c1d-4f37-b6a2-5d3e7c9a1b20",
    "created_at": "2026-11-04T12:00:00.000Z",
    "updated_at": "2026-11-04T12:00:00.000Z",
    "editable": true,
    "count": 21,
    "waiting_count": 15
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

GET /inbox-views/attribute-keys

Conversation-attribute keys and their common values

The workspace’s conversation-attribute keys (what the AI agent recorded with add_metadata, or a person set), most used first, each with count (conversations carrying it) and top_values — the top most frequent scalar values, cut to 120 characters — for a view editor’s picker. key narrows to one key.

ParameterInTypeRequiredConstraints
keyquerystringnomín. 1, máx. 120
limitqueryintegerno≥ 1, ≤ 200, por defecto 50
topqueryinteger | nullno≥ 0, ≤ 50, por defecto 5
curl https://api.vitrinadev.com/api/v1/inbox-views/attribute-keys \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": [
    {
      "key": "modelo",
      "count": 1334,
      "top_values": [
        {
          "value": "iPhone 18 Pro 256 GB",
          "count": 72
        },
        {
          "value": "iPhone 18 Pro Max",
          "count": 26
        }
      ]
    }
  ]
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /inbox-views/reorder

Reorder inbox views

Sets each listed view’s position to its index in ids. All ids must be views of scope that you write (workspace: routing:write; personal: your own); views left out keep their position. Answers the views you see, in their new order.

Body

FieldTypeRequiredConstraints
scopeworkspace \personalyes
idsuuid[]yes
curl -X POST https://api.vitrinadev.com/api/v1/inbox-views/reorder \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "workspace",
    "ids": [
      "6a1f0c7e-3b8d-4e52-9a51-0c2d7b1e9f44",
      "9d4b7a10-52c3-4e8f-a1b6-7e0c3f2d8a55"
    ]
  }'

Example response (200)

{
  "data": [
    {
      "id": "6a1f0c7e-3b8d-4e52-9a51-0c2d7b1e9f44",
      "name": "Piden 18 Pro Max",
      "scope": "workspace",
      "owner_user_id": null,
      "filters": {
        "active": true,
        "attributes": [
          {
            "key": "*",
            "op": "contains",
            "value": "18 pro max"
          }
        ]
      },
      "exclude_from_waiting": true,
      "position": 0,
      "created_by": "0b9e2f4a-8c1d-4f37-b6a2-5d3e7c9a1b20",
      "created_at": "2026-11-04T12:00:00.000Z",
      "updated_at": "2026-11-04T12:00:00.000Z",
      "editable": true,
      "count": 21,
      "waiting_count": 15
    }
  ]
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

VAT regime

Whether a car sells with VAT (afecto) or without it (exento): the dealership's default and the per-unit decision, captured at intake and never rewritten by a later default change.

Dealership insights

The Comisiones export for the month-end close, as Excel or CSV: one row per seller and deal with the commission arithmetic visible, and a summary of what each person is owed.

On this page

GET /inbox-viewsPOST /inbox-viewsDELETE /inbox-views/{id}GET /inbox-views/{id}PATCH /inbox-views/{id}GET /inbox-views/attribute-keysPOST /inbox-views/reorder