# custom_objects.records_query Listar registros de um objeto. Registros do objeto, 50 por página (`perPage` até 200). `filters` é uma lista (todos valem): `{fieldId, op, value}` com `fieldId` = id de um campo, `title`, `responsible` (id do responsável) ou `createdAt`/`updatedAt` (AAAA-MM-DD, compara o dia) e `op` em eq, neq, contains, not_contains, gt, gte, lt, lte, empty, not_empty, in, not_in, starts_with, ends_with. `relations` filtra por ligação (`{relationId, side, quantifier: any|all|none, value?, conditions?}`: o registro tem (algum, todos) ou não tem vínculo; `value` restringe ao outro lado cujo nome contém o texto e `conditions` (`{fieldId, op, value}`, as chaves vêm de `custom_objects.relation_filter_fields`) aos vínculos cujo outro lado cumpre todas as condições). Cada registro traz `relations` (por ligação e lado: `count` e `preview` com os 3 primeiros vínculos). `search` procura no título e nos textos. Ordem: `sortBy` (title, responsible, createdAt, updatedAt) ou `sortFieldId`, com `sortDir`; o padrão é o mais novo primeiro. `responsibleAttendantId` limita ao responsável. Cada registro traz `title` (valor do campo-título), `values` (`{: valor}`) e o responsável. `meta` traz página, total de páginas e de itens. - Endpoint: `POST https://app.atomiks.com.br/api/v1/custom_objects.records_query` (corpo JSON) - Quem pode chamar: membro da conta - Escopo da chave: `crm:read` - Grava dados: não - Pela chave de API: sim - Ferramenta MCP: `custom_objects_records_query` - Ficha em JSON: `https://app.atomiks.com.br/api/v1/openapi.json` (operationId `custom_objects.records_query`) ## Entrada | Campo | Tipo | Obrigatório | Nota | |---|---|---|---| | `objectId` | string (uuid) | sim | | | `filters` | object[] | não | | | `relations` | object[] | não | | | `search` | string | não | | | `responsibleAttendantId` | string (uuid) | não | | | `sortBy` | "title" \| "responsible" \| "createdAt" \| "updatedAt" | não | | | `sortFieldId` | string (uuid) | não | | | `sortDir` | "asc" \| "desc" | não | | | `page` | integer | não | | | `perPage` | integer | não | |
JSON Schema ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "objectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "filters": { "maxItems": 30, "type": "array", "items": { "type": "object", "properties": { "fieldId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "string", "enum": [ "title", "responsible", "createdAt", "updatedAt" ] } ] }, "op": { "type": "string", "enum": [ "eq", "neq", "contains", "not_contains", "gt", "gte", "lt", "lte", "empty", "not_empty", "in", "not_in", "starts_with", "ends_with" ] }, "value": {} }, "required": [ "fieldId", "op" ] } }, "relations": { "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "relationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "side": { "type": "string", "enum": [ "source", "target" ] }, "quantifier": { "type": "string", "enum": [ "any", "all", "none" ] }, "value": { "type": "string", "maxLength": 200 }, "conditions": { "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "fieldId": { "type": "string", "minLength": 1, "maxLength": 80 }, "op": { "type": "string", "enum": [ "eq", "neq", "contains", "not_contains", "gt", "gte", "lt", "lte", "empty", "not_empty", "in", "not_in", "starts_with", "ends_with" ] }, "value": {} }, "required": [ "fieldId", "op" ] } } }, "required": [ "relationId", "side", "quantifier" ] } }, "search": { "type": "string", "maxLength": 200 }, "responsibleAttendantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sortBy": { "type": "string", "enum": [ "title", "responsible", "createdAt", "updatedAt" ] }, "sortFieldId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sortDir": { "type": "string", "enum": [ "asc", "desc" ] }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 200 } }, "required": [ "objectId" ] } ```
## Exemplo ```bash curl -X POST https://app.atomiks.com.br/api/v1/custom_objects.records_query \ -H "Authorization: Bearer $ATOMIKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"objectId":"00000000-0000-0000-0000-000000000000","search":"centro"}' ``` CLI: ```bash node cli/atomiks.mjs custom_objects.records_query --json '{"objectId":"00000000-0000-0000-0000-000000000000","search":"centro"}' ``` MCP: ferramenta `custom_objects_records_query` 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": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "objectId": { "type": "string" }, "title": { "type": "string" }, "values": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "responsibleAttendantId": { "type": [ "string", "null" ] }, "responsibleAttendantName": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "relations": { "type": "array", "items": { "type": "object", "properties": { "relationId": { "type": "string" }, "side": { "type": "string", "enum": [ "source", "target" ] }, "count": { "type": "number" }, "preview": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" } }, "required": [ "id", "label" ], "additionalProperties": false } } }, "required": [ "relationId", "side", "count", "preview" ], "additionalProperties": false } } }, "required": [ "id", "objectId", "title", "values", "responsibleAttendantId", "responsibleAttendantName", "createdAt", "updatedAt" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "page": { "type": "number" }, "perPage": { "type": "number" }, "countPages": { "type": "number" }, "countItens": { "type": "number" } }, "required": [ "page", "perPage", "countPages", "countItens" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "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).