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

{
  "$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"
  ]
}

Exemplo

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:

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.

{
  "$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).