> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Visão geral da API GraphQL

> Consulte operações de redes sociais suportadas pelo Ayrshare por meio de um único endpoint GraphQL.

A API GraphQL expõe um subconjunto suportado dos recursos REST do Ayrshare por meio de um único endpoint. Cada campo exposto chama o mesmo controlador subjacente que sua contraparte REST, então autenticação, permissões, cotas e dados de resposta seguem o comportamento do REST. O REST continua sendo a API mais ampla; use o schema ou o Explorer para ver exatamente quais operações o GraphQL suporta.

O que ele acrescenta é a possibilidade de pedir várias coisas em uma única requisição e de descobrir a superfície GraphQL atualmente suportada a partir do próprio schema, sem ler a documentação página por página. O schema descreve cada campo de requisição suportado e as seleções tipadas disponíveis em respostas estruturadas; operações que retornam o envelope REST como `JSON` preservam esse payload completo.

```
https://api.ayrshare.com/graphql
```

Envie um `POST` com um corpo JSON contendo uma `query`, exatamente como em qualquer endpoint GraphQL. `GET` e `DELETE` retornam `405 Method Not Allowed` — consultas via `GET` são opcionais na especificação GraphQL e não são suportadas aqui.

<h2 id="your-first-query">
  Sua primeira consulta
</h2>

```bash theme={"system"}
curl -X POST https://api.ayrshare.com/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ postHistory(lastDays: 7) }"}'
```

A resposta é o mesmo envelope JSON que o [endpoint REST de histórico](/docs/apis/history/get-history) retorna, encapsulado no campo `data` do GraphQL:

```json theme={"system"}
{
  "data": {
    "postHistory": {
      "history": [
        { "id": "RkQ8uXg2jT7bNd1Wq0Ya", "status": "success", "post": "Hello world" }
      ],
      "refId": "9d2a7c41f0b8e6d35a1c",
      "count": 1,
      "lastUpdated": "2026-09-24T12:00:00.000Z",
      "nextUpdate": "2026-09-24T12:00:00.000Z"
    }
  }
}
```

<h2 id="asking-for-several-things-at-once">
  Pedindo várias coisas de uma vez
</h2>

O motivo para recorrer ao GraphQL é uma requisição como esta, que seriam quatro chamadas REST:

```graphql theme={"system"}
{
  history: postHistory(lastDays: 7)
  accounts: user
  comments: comments(id: "abc123")
  analytics: socialAnalytics(platforms: [INSTAGRAM])
}
```

Uma única ida e volta retorna as quatro. Observe que são **quatro campos de operação raiz e quatro chamadas de API para fins de cobrança**, e não uma. Selecionar campos aninhados da resposta não adiciona chamadas — veja [Limites e cobrança](/docs/apis/graphql/limits).

<h2 id="authentication">
  Autenticação
</h2>

Idêntica ao REST. Envie sua API Key como um bearer token:

```
Authorization: Bearer YOUR_API_KEY
```

Se sua conta usa User Profiles, as operações que expõem `profileKey` podem selecionar um perfil de duas formas:

<ul class="custom-bullets">
  <li>Envie <code>Profile-Key</code> como padrão para toda a requisição.</li>
  <li>Passe <code>profileKey</code> em um campo individual para sobrescrever esse padrão, permitindo que uma única requisição atue em mais de um perfil.</li>
</ul>

O argumento do campo prevalece quando ambos estão presentes. Campos no nível da conta ou exclusivos da conta principal não expõem `profileKey` e podem rejeitar um cabeçalho `Profile-Key`; por exemplo, `createProfile` deve usar a API Key principal sem esse cabeçalho. Verifique a definição de schema de cada campo para saber seu escopo e veja [Gerenciando vários usuários](/docs/multiple-users/business-plan-overview) para entender como as Profile Keys funcionam.

<h2 id="try-it-without-writing-code">
  Experimente sem escrever código
</h2>

O [GraphQL Explorer](https://app.ayrshare.com/graphql-explorer) é um navegador interativo do schema atual. Ele lista todas as operações GraphQL disponíveis com seus argumentos e descrições, oferece autocompletar enquanto você digita e executa consultas na sua conta.

Você não precisa de uma API Key para navegar pelo schema — o schema é público, assim como esta documentação. Você precisa de uma para executar uma consulta, porque toda operação passa pela mesma autenticação do REST.

<h2 id="should-you-use-graphql-or-rest">
  Você deve usar GraphQL ou REST?
</h2>

O REST continua sendo a interface principal e aquela em torno da qual a maior parte da nossa documentação, dos [SDKs](/docs/packages-guides/overview) e das integrações foi construída. Recorra ao GraphQL quando:

<ul class="custom-bullets">
  <li>Você precisa de várias informações não relacionadas e quer obtê-las em uma única ida e volta.</li>
  <li>Você quer nomes de operações, argumentos, objetos de entrada, enums e seleções de resposta tipadas legíveis por máquina. A maioria das respostas continua sendo <code>JSON</code> para preservar o envelope REST completo; <code>createPost</code> atualmente retorna um <code>PostResult</code> tipado.</li>
  <li>Você está explorando a API e quer ver o que existe sem navegar entre páginas da documentação.</li>
</ul>

Continue com o REST quando:

<ul class="custom-bullets">
  <li>Você está enviando arquivos. Os bytes de mídia não podem trafegar por uma requisição GraphQL — veja <a href="/docs/apis/graphql/using-the-api#uploading-media">Upload de mídia</a> para o caminho suportado.</li>
  <li>Você está usando um de nossos <a href="/docs/packages-guides/overview">SDKs ou integrações no-code</a>, que usam REST.</li>
  <li>Você quer o menor número possível de dependências. Uma chamada REST não precisa de nada além de um cliente HTTP.</li>
</ul>

As duas interfaces são suportadas lado a lado, e você pode combiná-las livremente na mesma integração.

<h2 id="read-next">
  Leia a seguir
</h2>

<ul class="custom-bullets">
  <li>[Usando a API](/docs/apis/graphql/using-the-api) — como encontrar operações, tipos de argumentos e upload de mídia.</li>
  <li>[Erros](/docs/apis/graphql/errors) — quais falhas alteram o status HTTP, por que operações com falha ainda retornam HTTP 200 e como lidar com sucesso parcial.</li>
  <li>[Limites e cobrança](/docs/apis/graphql/limits) — limites de tamanho de consulta e como as requisições são contabilizadas.</li>
</ul>