{
  "openapi": "3.1.0",
  "info": {
    "title": "Trafexa Assistant API",
    "version": "0.2.0",
    "description": "OpenAPI multi-tenant das mesmas operações do MCP Trafexa. Cada request usa o Bearer do usuário (Integrações → Assistente IA). Não há token compartilhado no servidor."
  },
  "servers": [
    {
      "url": "https://mcp.trafexa.com.br"
    }
  ],
  "paths": {
    "/api/me": {
      "get": {
        "operationId": "me",
        "summary": "Usuário e agências",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/assistant/tools/whoami": {
      "post": {
        "operationId": "whoami",
        "summary": "Retorna o usuário autenticado, agências e escopos do token do assistente.",
        "tags": [
          "agency"
        ],
        "x-trafexa-ability": "agency:read",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado da tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/assistant/tools/list_agencies": {
      "post": {
        "operationId": "list_agencies",
        "summary": "Lista as agências do usuário autenticado.",
        "tags": [
          "agency"
        ],
        "x-trafexa-ability": "agency:read",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado da tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/assistant/tools/list_clients": {
      "post": {
        "operationId": "list_clients",
        "summary": "Lista clientes da agência (busca opcional).",
        "tags": [
          "clients"
        ],
        "x-trafexa-ability": "clients:read",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agency_id": {
                    "type": "number"
                  },
                  "q": {
                    "type": "string"
                  },
                  "page": {
                    "type": "number"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado da tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/assistant/tools/get_client": {
      "post": {
        "operationId": "get_client",
        "summary": "Detalha um cliente da agência.",
        "tags": [
          "clients"
        ],
        "x-trafexa-ability": "clients:read",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agency_id": {
                    "type": "number"
                  },
                  "client_id": {
                    "type": "number"
                  }
                },
                "required": [
                  "client_id"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado da tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/assistant/tools/list_task_spaces": {
      "post": {
        "operationId": "list_task_spaces",
        "summary": "Lista espaços/boards/grupos de tarefas da agência.",
        "tags": [
          "tasks"
        ],
        "x-trafexa-ability": "tasks:read",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agency_id": {
                    "type": "number"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado da tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/assistant/tools/search_tasks": {
      "post": {
        "operationId": "search_tasks",
        "summary": "Busca tarefas por texto e/ou cliente.",
        "tags": [
          "tasks"
        ],
        "x-trafexa-ability": "tasks:read",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agency_id": {
                    "type": "number"
                  },
                  "q": {
                    "type": "string"
                  },
                  "client_id": {
                    "type": "number"
                  },
                  "limit": {
                    "type": "number"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado da tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/assistant/tools/create_task": {
      "post": {
        "operationId": "create_task",
        "summary": "Cria uma tarefa em um grupo (task_group_id).",
        "tags": [
          "tasks"
        ],
        "x-trafexa-ability": "tasks:write",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agency_id": {
                    "type": "number"
                  },
                  "task_group_id": {
                    "type": "number"
                  },
                  "title": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string"
                  },
                  "priority": {
                    "type": "string"
                  },
                  "due_on": {
                    "type": "string"
                  },
                  "assignee_id": {
                    "type": "number"
                  }
                },
                "required": [
                  "task_group_id"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado da tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/assistant/tools/update_task": {
      "post": {
        "operationId": "update_task",
        "summary": "Atualiza campos de uma tarefa existente.",
        "tags": [
          "tasks"
        ],
        "x-trafexa-ability": "tasks:write",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agency_id": {
                    "type": "number"
                  },
                  "task_id": {
                    "type": "number"
                  },
                  "title": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string"
                  },
                  "priority": {
                    "type": "string"
                  },
                  "due_on": {
                    "type": "string"
                  },
                  "assignee_id": {
                    "anyOf": [
                      {
                        "type": "number"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "task_group_id": {
                    "type": "number"
                  }
                },
                "required": [
                  "task_id"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado da tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/assistant/tools/list_social_accounts": {
      "post": {
        "operationId": "list_social_accounts",
        "summary": "Lista contas sociais (Meta) conectadas na agência.",
        "tags": [
          "social"
        ],
        "x-trafexa-ability": "social:read",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agency_id": {
                    "type": "number"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado da tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/assistant/tools/list_social_posts": {
      "post": {
        "operationId": "list_social_posts",
        "summary": "Lista postagens sociais da agência.",
        "tags": [
          "social"
        ],
        "x-trafexa-ability": "social:read",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agency_id": {
                    "type": "number"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado da tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/assistant/tools/get_social_insights": {
      "post": {
        "operationId": "get_social_insights",
        "summary": "Insights de uma postagem social publicada.",
        "tags": [
          "social"
        ],
        "x-trafexa-ability": "social:read",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agency_id": {
                    "type": "number"
                  },
                  "social_post_id": {
                    "type": "number"
                  }
                },
                "required": [
                  "social_post_id"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado da tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/assistant/tools/update_social_post": {
      "post": {
        "operationId": "update_social_post",
        "summary": "Atualiza legenda/agendamento de rascunho, agendada ou falha. Para publicar/agendar use mode. Mídia não é alterada por esta tool.",
        "tags": [
          "social"
        ],
        "x-trafexa-ability": "social:write",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agency_id": {
                    "type": "number"
                  },
                  "social_post_id": {
                    "type": "number"
                  },
                  "caption": {
                    "type": "string"
                  },
                  "title": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "rascunho",
                      "agendar",
                      "agora"
                    ]
                  },
                  "scheduled_at": {
                    "type": "string"
                  }
                },
                "required": [
                  "social_post_id"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado da tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/assistant/tools/retry_social_post": {
      "post": {
        "operationId": "retry_social_post",
        "summary": "Reenvia redes que falharam em uma postagem.",
        "tags": [
          "social"
        ],
        "x-trafexa-ability": "social:publish",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agency_id": {
                    "type": "number"
                  },
                  "social_post_id": {
                    "type": "number"
                  },
                  "networks": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "facebook",
                        "instagram"
                      ]
                    }
                  }
                },
                "required": [
                  "social_post_id"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado da tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/assistant/tools/list_campaigns": {
      "post": {
        "operationId": "list_campaigns",
        "summary": "Lista campanhas Meta Ads (nível campanhas).",
        "tags": [
          "ads"
        ],
        "x-trafexa-ability": "ads:read",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agency_id": {
                    "type": "number"
                  },
                  "client_id": {
                    "type": "number"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado da tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/assistant/tools/list_meetings": {
      "post": {
        "operationId": "list_meetings",
        "summary": "Lista reuniões da agência.",
        "tags": [
          "meetings"
        ],
        "x-trafexa-ability": "meetings:read",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agency_id": {
                    "type": "number"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado da tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/assistant/tools/create_meeting": {
      "post": {
        "operationId": "create_meeting",
        "summary": "Cria uma reunião (presencial/online, equipe/pessoal).",
        "tags": [
          "meetings"
        ],
        "x-trafexa-ability": "meetings:write",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agency_id": {
                    "type": "number"
                  },
                  "title": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "observations": {
                    "type": "string"
                  },
                  "starts_at": {
                    "type": "string"
                  },
                  "ends_at": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "presencial",
                      "online"
                    ]
                  },
                  "visibility": {
                    "type": "string",
                    "enum": [
                      "personal",
                      "team"
                    ]
                  },
                  "location": {
                    "type": "string"
                  },
                  "client_id": {
                    "type": "number"
                  },
                  "participant_ids": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    }
                  }
                },
                "required": [
                  "title",
                  "starts_at",
                  "type",
                  "visibility"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado da tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/assistant/tools/update_meeting": {
      "post": {
        "operationId": "update_meeting",
        "summary": "Atualiza uma reunião existente.",
        "tags": [
          "meetings"
        ],
        "x-trafexa-ability": "meetings:write",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agency_id": {
                    "type": "number"
                  },
                  "meeting_id": {
                    "type": "number"
                  },
                  "title": {
                    "type": "string"
                  },
                  "description": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "observations": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "starts_at": {
                    "type": "string"
                  },
                  "ends_at": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "presencial",
                      "online"
                    ]
                  },
                  "visibility": {
                    "type": "string",
                    "enum": [
                      "personal",
                      "team"
                    ]
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "agendada",
                      "realizada",
                      "cancelada"
                    ]
                  },
                  "location": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "client_id": {
                    "anyOf": [
                      {
                        "type": "number"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "participant_ids": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    }
                  }
                },
                "required": [
                  "meeting_id"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado da tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/assistant/tools/finance_summary": {
      "post": {
        "operationId": "finance_summary",
        "summary": "Resumo financeiro da agência.",
        "tags": [
          "finance"
        ],
        "x-trafexa-ability": "finance:read",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agency_id": {
                    "type": "number"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado da tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/assistant/tools/list_finance_items": {
      "post": {
        "operationId": "list_finance_items",
        "summary": "Lista obrigações/itens financeiros (filtros opcionais).",
        "tags": [
          "finance"
        ],
        "x-trafexa-ability": "finance:read",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agency_id": {
                    "type": "number"
                  },
                  "direction": {
                    "type": "string",
                    "enum": [
                      "in",
                      "out"
                    ]
                  },
                  "status": {
                    "type": "string"
                  },
                  "control": {
                    "type": "string",
                    "enum": [
                      "mes_atual",
                      "atrasados",
                      "proximos_30",
                      "abertos",
                      "pagos"
                    ]
                  },
                  "q": {
                    "type": "string"
                  },
                  "page": {
                    "type": "number"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado da tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/assistant/tools/list_contracts": {
      "post": {
        "operationId": "list_contracts",
        "summary": "Lista contratos da agência.",
        "tags": [
          "contracts"
        ],
        "x-trafexa-ability": "contracts:read",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agency_id": {
                    "type": "number"
                  },
                  "q": {
                    "type": "string"
                  },
                  "client_id": {
                    "type": "number"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "rascunho",
                      "em_analise",
                      "aguardando_assinatura",
                      "ativo",
                      "suspenso",
                      "encerrado",
                      "cancelado"
                    ]
                  },
                  "page": {
                    "type": "number"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado da tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/assistant/tools/get_contract": {
      "post": {
        "operationId": "get_contract",
        "summary": "Detalha um contrato.",
        "tags": [
          "contracts"
        ],
        "x-trafexa-ability": "contracts:read",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agency_id": {
                    "type": "number"
                  },
                  "contract_id": {
                    "type": "number"
                  }
                },
                "required": [
                  "contract_id"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado da tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/assistant/tools/list_notifications": {
      "post": {
        "operationId": "list_notifications",
        "summary": "Lista notificações da inbox do usuário na agência.",
        "tags": [
          "notifications"
        ],
        "x-trafexa-ability": "notifications:read",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agency_id": {
                    "type": "number"
                  },
                  "tab": {
                    "type": "string",
                    "enum": [
                      "notifications",
                      "mentions",
                      "all"
                    ]
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado da tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Sanctum"
      }
    }
  }
}