> This page is for Plataforma, version Herdado. > For other versions, use one of these documentation indexes: > - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt > - V4 experimental: https://next.developer.frame.io/platform/v4-experimental/llms.txt > - Herdado: https://next.developer.frame.io/platform/v2/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://next.developer.frame.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server. # Pesquisar ativos # Visão geral A API do Frame.io oferece suporte à pesquisa profunda e facetada de ativos em uma conta inteira, espelhando a funcionalidade no aplicativo web.Embora os filtros mais úteis sejam equipe, projeto e status, os filtros e a classificação podem ser combinados de maneiras únicas para produzir conjuntos extremamente específicos orientados por API.Em geral, todos os filtros, exceto `account_id`, `q` (consulta) e `sort`, seguem a mesma estrutura e todos são explicados abaixo. search-filters.png Desde março de 2022, há um bug conhecido que afeta a função de paginação da API de pesquisa.Até que esse bug seja corrigido, não recomendamos usar a API de pesquisa para iterar em várias páginas de resultados (ou seja, mais de 100 ativos), porque o tamanho da página solicitada pode não corresponder à contagem real de ativos retornados. ## Padrões A solicitação da API para acionar uma pesquisa é sempre a mesma: É sempre a mesma solicitação `POST` para `https://api.frame.io/v2/search/library` Se não for fornecido explicitamente, os valores padrão para ajuste de pesquisa são os seguintes: | Atributo | Valor padrão | Descrição | |:--------|:------------|:----------| | `page_size` | 10 | 10 ativos serão retornados por página. | | `page` | 1 | A consulta retornará a primeira página da resposta. | | `sort` | `relevance` | "Relevância" tenta ordenar ativos com base em um conjunto de atributos especificamente ajustados.Na ausência de uma consulta, a relevância é fortemente influenciada pela data de upload mais recente. | ## Sobre este guia Este guia explica o processo de criação de uma consulta de pesquisa que corresponda a: * Ativos dentro de uma conta * Que corresponde à consulta `"moon"` * Está em um projeto específico * Foi carregado entre 1º e 30 de abril de 2020 * E foi "Aprovado" O corpo da nossa pesquisa ficará assim: ```json { "account_id": "", "q": "moon", "sort": "name", "filter": { "inserted_at": [ { "op": "gte", "value": "2020-04-01T04:00:00.000Z" }, { "op": "lte", "value": "2020-04-30T03:59:59.999Z" } ], "project_id": { "op": "eq", "value": "" }, "label": { "op": "eq", "value": "approved" } }, "page_size": 10, "page": 1 } ``` ### Conta, consulta e classificação A Conta (`account_id`), consulta (`q`) e `sort` são os três blocos básicos mais importantes que ficam fora de qualquer atributo de `filter` em uma consulta de pesquisa. #### Contexto da conta Tecnicamente, o único atributo necessário para realizar uma pesquisa é um `account_id`.Fazer isso simplesmente obterá todos os ativos (incluindo pastas) na conta, com valores de paginação padrão (10 ativos por página, começando na página 1). ```json { "account_id": "" } ``` #### Pesquisar consulta O próximo atributo mais comum (e útil) a incluir é a própria consulta.Observação: como a pesquisa da API do Frame.io aceita uma consulta nula, não há necessidade de uma consulta curinga (`*`).Você está pesquisando algo ou solicitando uma classificação (potencialmente filtrada) de todos os ativos em uma conta. No nosso caso, vamos pesquisar o termo "moon". ```json { "account_id": "", "q": "moon" } ``` ### Classificação sort.png O Frame.io oferece suporte a várias opções de classificação diferentes.A sintaxe para ordem de classificação é semelhante entre as opções: * Há uma direção de classificação padrão * Para inverter essa direção, adicione o prefixo `-` negativo ao valor de classificação Por exemplo, para classificar em ordem alfabética reversa (Z a A), você declararia `"sort": "-name"`.A operação de classificação padrão é "Relevância".Consequentemente, não precisa ser declarada e será assumida se nenhum atributo `sort` for fornecido. | Opção de classificação | Atributo | Direção padrão | |:----------|:--------|:----------------| | **Relevância** | n/d | n/d | | **Data do upload** | `inserted_at` | Mais antigo primeiro | | **Nome** | `name` | De A a Z. | | **Tamanho** | `filesize` | Menor primeiro | | **Carregador** | `creator.name` | De A a Z. | Assim, conforme criamos nossa consulta, podemos agora adicionar nossa classificação (`sort`) por `name`, de A a Z: ```json { "account_id": "", "q": "moon", "sort": "name" } ``` ### Filtros e paginação Os filtros são ao mesmo tempo o recurso mais difícil e mais poderoso da pesquisa de ativos do Frame.io.Os filtros são escritos dentro de um único objeto `filter` e todos seguem o mesmo padrão de uma operação (`op`) e um `value`. Os filtros usam as seguintes abreviações comuns, com opções de equivalência diferentes de "igual a" reservadas para consultas de data e tamanho: * `eq` — igual a * `lt` — menor que * `gt` — maior que * `lte` — menor ou igual a * `gte` — maior ou igual a * `match` — combinação exata, usado apenas para filtros de Carregador e Tipo de arquivo Por exemplo, um `filter` para combinação em um `project_id` conhecido seria construído da seguinte forma: ```json { "filter": { "project_id": { "op": "eq", "value": "" } } } ``` ### Opções e operações A tabela a seguir descreve as opções e operações associadas a cada tipo de filtro. | Opção de filtro | Atributo | Operações compatíveis | Valores compatíveis | |:------------|:--------|:-------------------|:---------------| | **Arquivado** | `archived` | `eq` | `true`, `false` | | **Data do upload** | `inserted_at` | `eq`, `lt`, `gt`, `lte`, `gte` | `<datetime>` (ISO-8601, UTC) | | **Excluído** | `deleted` | `eq` | `true`, `false` | | **Tipo de arquivo** | `filetype` | `match` | `` | | **Particular** | `private` | `eq` | `true`, `false` | | **Projeto** | `project_id` | `eq` | `<project_id>` | | **Tamanho** | `filesize` | `eq`, `lt`, `gt`, `lte`, `gte` | `size` (em bytes) | | **Status** | `label` | `eq` | `none`, `in_progress`, `needs_review`, `approved` | | **Equipe** | `team_id` | `eq` | `<team_id>` | | **Tipo** | `asset_type` | `eq` | `audio`, `document`, `folder`, `image`, `other`, `stream`, `video` | | **Carregador** | `creator.name` | `match` | `<name>` | A pesquisa por criadores que não são mais membros da conta não funcionará, pois esse usuário não está mais no índice de pesquisa de usuários. Para continuar criando nossa consulta, agora podemos adicionar um filtro para ativos que são: * Está em um projeto específico * Upload feito entre 1º e 30 de abril de 2020 * Marcado como "Aprovado" ```json { "account_id": "", "q": "moon", "sort": "name", "filter": { "inserted_at": [ { "op": "gte", "value": "2020-04-01T04:00:00.000Z" }, { "op": "lte", "value": "2020-04-28T03:59:59.999Z" } ], "project_id": { "op": "eq", "value": "" }, "label": { "op": "eq", "value": "approved" } } } ``` O ponto de acesso de pesquisa pagina exatamente como qualquer outro ponto de acesso, por meio dos atributos `page_size` e `page` que ficam na camada mais externa do corpo da solicitação.Para mais detalhes sobre paginação, consulte o guia separado [aqui](/platform/v2/key-concepts#pagination).