# search.global

Busca global (paleta ⌘K). Busca por nome em contatos (nome, telefone, e-mail, instagram), oportunidades, listas, segmentos, tags, pipelines, flows e produtos da conta atual. `q` com 2+ caracteres; `types` restringe os tipos; `limit` por tipo (até 20, padrão 5). Volta grupos na ordem fixa dos tipos, sem grupo vazio, cada item com `href` para abrir no app. Tipos sem acesso (plano, permissão do membro ou escopo da chave) ficam de fora sem erro.

- Endpoint: `POST https://app.atomiks.com.br/api/v1/search.global` (corpo JSON)
- Quem pode chamar: membro da conta
- Escopo da chave: nenhum (qualquer chave serve)
- Grava dados: não
- Pela chave de API: sim
- Ferramenta MCP: `search_global`
- Ficha em JSON: `https://app.atomiks.com.br/api/v1/openapi.json` (operationId `search.global`)

## Entrada

| Campo | Tipo | Obrigatório | Nota |
|---|---|---|---|
| `q` | string | sim |  |
| `types` | "contact" \| "opportunity" \| "list" \| "segment" \| "tag" \| "pipeline" \| "flow" \| "product"[] | não |  |
| `limit` | integer | não | padrão 5 |

<details><summary>JSON Schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "minLength": 2,
      "maxLength": 100
    },
    "types": {
      "maxItems": 8,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "contact",
          "opportunity",
          "list",
          "segment",
          "tag",
          "pipeline",
          "flow",
          "product"
        ]
      }
    },
    "limit": {
      "default": 5,
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    }
  },
  "required": [
    "q"
  ]
}
```

</details>

## Exemplo

```bash
curl -X POST https://app.atomiks.com.br/api/v1/search.global \
  -H "Authorization: Bearer $ATOMIKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"maria","types":["contact","opportunity"],"limit":5}'
```

CLI:

```bash
node cli/atomiks.mjs search.global --json '{"q":"maria","types":["contact","opportunity"],"limit":5}'
```

MCP: ferramenta `search_global` com a mesma entrada.

## Saída

Sucesso: `{"data": ...}` com o formato abaixo.

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "groups": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "contact",
              "opportunity",
              "list",
              "segment",
              "tag",
              "pipeline",
              "flow",
              "product"
            ]
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "contact",
                    "opportunity",
                    "list",
                    "segment",
                    "tag",
                    "pipeline",
                    "flow",
                    "product"
                  ]
                },
                "id": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "subtitle": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "href": {
                  "type": "string"
                },
                "status": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "valueCents": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "color": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "emoji": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "thumbnailUrl": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "updatedAt": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "type",
                "id",
                "title",
                "subtitle",
                "href",
                "status",
                "valueCents",
                "color",
                "emoji",
                "thumbnailUrl",
                "updatedAt"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "type",
          "items"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "groups"
  ],
  "additionalProperties": false
}
```

## Erros

`{"error": {"code", "message", "requestId"}}`. Códigos: `invalid_input` (400), `unauthorized` (401), `forbidden` / `account_pending` / `scope_missing` (403), `not_found` (404), `limit_reached` (409), `internal` (500).