> ## 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.

# Usando a API GraphQL

> Encontre operações, entenda tipos de argumentos e enums, crie publicações e faça upload de mídia pela API GraphQL do Ayrshare.

<h2 id="finding-an-operation">
  Encontrando uma operação
</h2>

O schema é a fonte oficial para o subconjunto GraphQL suportado: raízes de operação, nomes, argumentos, tipos de entrada e valores de enum. As descrições fornecem orientações de uso, e o [GraphQL Explorer](https://app.ayrshare.com/graphql-explorer) expõe ambos. Para recursos disponíveis apenas no REST, use a [referência da REST API](/docs/apis/overview).

Os nomes das operações seguem os endpoints REST que acessam, em camelCase. `GET /history` é `postHistory`, `GET /analytics/social` é `socialAnalytics`, `POST /post` é `createPost`.

<h2 id="queries-read-mutations-write">
  Queries leem, mutations escrevem
</h2>

Queries são leituras e validações que não alteram nada do nosso lado. Mutations publicam ou alteram estado, iniciam trabalhos ou enviam e-mails. Nem o verbo HTTP do REST nem o custo de uma chamada determinam a raiz:

<ul class="custom-bullets">
  <li><code>validatePost</code> verifica uma publicação sem publicá-la.</li>
  <li><code>validateMedia</code> verifica se uma URL de mídia está acessível.</li>
  <li><code>generatePost</code> é uma query porque nada muda do nosso lado. Ainda assim, ela conta como uma chamada de API e retorna um texto diferente a cada vez, então garanta que um cache do cliente ou um refetch automático não a repita sem que você perceba.</li>
  <li><code>mediaUploadUrl</code> é uma mutation porque cria uma URL de upload para sua conta.</li>
  <li><code>linkAnalytics</code> é uma mutation porque pode solicitar um relatório por e-mail.</li>
  <li><code>userBatch</code> é uma mutation porque inicia um trabalho de exportação.</li>
</ul>

Use o Explorer ou o schema para confirmar a raiz de cada operação suportada.

<h2 id="creating-a-post">
  Criando uma publicação
</h2>

`createPost` recebe um único argumento `input`, então a publicação inteira é um objeto:

```graphql theme={"system"}
mutation {
  createPost(input: {
    post: "Hello from GraphQL"
    platforms: [LINKEDIN]
    idempotencyKey: "post-2026-09-01-001"
  }) {
    status
    id
  }
}
```

O input espelha o [endpoint REST de publicação](/docs/apis/post/post) documentado, incluindo os objetos de opções por rede e as formas do REST que aceitam mais de um formato JSON:

```graphql theme={"system"}
mutation {
  createPost(input: {
    post: "New video"
    platforms: [YOUTUBE]
    mediaUrls: ["https://example.com/video.mp4"]
    idempotencyKey: "youtube-video-001"
    youTubeOptions: {
      title: "My video"
      visibility: PUBLIC
    }
  }) {
    status
    id
    postIds { platform postUrl }
  }
}
```

Uma publicação pode ter sucesso em uma rede e falhar em outra. Isso não é uma falha da requisição — veja [Erros](/docs/apis/graphql/errors#partial-success-on-multi-network-posts).

<h2 id="argument-types">
  Tipos de argumentos
</h2>

A maioria dos argumentos são strings, números e booleanos comuns. Vale a pena conhecer três casos.

<h3 id="enums">
  Enums
</h3>

Muitos argumentos de string com um conjunto fechado de valores suportados são enums GraphQL, escritos **sem aspas e em maiúsculas**:

```graphql theme={"system"}
{ socialAnalytics(platforms: [INSTAGRAM, TIKTOK]) }
```

Não `"instagram"`. O servidor mapeia cada enum aceito para o valor exato esperado pelo controlador REST subjacente — geralmente, mas nem sempre, uma string em minúsculas. Um enum inválido é rejeitado durante a validação GraphQL, antes de a operação ser executada, então um erro de digitação não custa nada.

Alguns argumentos compartilham o mesmo nome entre operações, mas aceitam valores diferentes, porque os endpoints realmente diferem. `reviews(platform:)` aceita apenas `GMB` e `FACEBOOK`, já que essas são as únicas redes com avaliações. O autocompletar do seu cliente mostrará o conjunto correto para cada operação.

<h3 id="the-json-scalar">
  O scalar JSON
</h3>

Alguns argumentos são tipados como `JSON` em vez de um tipo específico. Isso acontece quando um valor legitimamente tem mais de um formato e nenhum tipo GraphQL único conseguiria descrevê-lo com fidelidade:

<ul class="custom-bullets">
  <li><code>explainError(code:)</code> aceita <code>215</code> ou <code>"215"</code>, porque os clientes armazenam códigos de erro das duas formas.</li>
  <li><code>createPost(input:)</code> usa JSON para campos como <code>post</code> e <code>mediaUrls</code>, que podem ser valores compartilhados ou objetos por plataforma.</li>
  <li><code>createAutomation(triggers:, actions:)</code> recebem arrays cujos campos dependem do <code>type</code> de cada entrada.</li>
  <li><code>boostFacebookPost(interests:)</code> aceita ids de interesses da Meta como strings ou números.</li>
</ul>

Passe o mesmo valor que você enviaria no corpo REST correspondente. Um argumento `JSON` não é uma brecha: o resolver o valida antes do envio, então um valor inválido retorna um erro de validação e não consome nenhuma chamada de API.

<h3 id="optional-arguments-and-nulls">
  Argumentos opcionais e nulls
</h3>

Para argumentos opcionais e campos opcionais dentro de objetos de entrada, um `null` explícito é normalizado como omissão. Membros nulos dentro de listas são preservados quando o tipo da lista os permite.

<h2 id="reading-responses">
  Lendo respostas
</h2>

A maioria das operações retorna um scalar `JSON` contendo o envelope completo da resposta REST, então selecione o campo raiz sem subcampos. `createPost` atualmente retorna um `PostResult` tipado, então selecione seus campos:

```graphql theme={"system"}
mutation {
  createPost(input: {
    post: "Hi"
    platforms: [LINKEDIN]
    idempotencyKey: "linkedin-hi-001"
  }) {
    status
    id
    postIds { platform postUrl }
    errors { platform message code }
  }
}
```

Tipos de resposta tipados como `PostResult` também incluem `raw: JSON!`, contendo a resposta REST completa e sem modificações:

```graphql theme={"system"}
mutation {
  createPost(input: {
    post: "Hi"
    platforms: [LINKEDIN]
    idempotencyKey: "linkedin-hi-001"
  }) {
    status
    raw
  }
}
```

`raw` é permanente e existe para que um novo campo que apareça na resposta REST nunca fique inacessível pelo GraphQL enquanto ainda não o tipamos. Se você precisar de algo que os campos tipados não expõem, solicite `raw`.

<h2 id="uploading-media">
  Upload de mídia
</h2>

**Os bytes de mídia não podem trafegar por uma requisição GraphQL.** Uma requisição GraphQL é um único documento JSON com limite de 64 KB, então não há nenhum campo que aceite um arquivo, e codificar uma imagem em base64 dentro da consulta excederia esse limite para qualquer coisa maior que uma miniatura.

O caminho suportado evita o problema por completo e, de qualquer forma, é mais rápido do que fazer upload por meio de uma API, porque seus bytes vão direto para o armazenamento:

1. Solicite uma URL de upload:

   ```graphql theme={"system"}
   mutation { mediaUploadUrl(contentType: "image/jpeg") }
   ```

2. Leia `data.mediaUploadUrl.uploadUrl`, `accessUrl` e `contentType` do JSON retornado.

3. Faça um `PUT` do seu arquivo **diretamente para `uploadUrl`**, e não para a API do Ayrshare, definindo o cabeçalho `Content-Type` da requisição com o `contentType` retornado.

4. Depois que o upload for concluído, passe `accessUrl` em `createPost.input.mediaUrls`:

   ```graphql theme={"system"}
   mutation {
     createPost(input: {
       post: "With a photo"
       platforms: [INSTAGRAM]
       mediaUrls: ["https://the-returned-access-url"]
       idempotencyKey: "instagram-photo-001"
     }) {
       status
       postIds { platform postUrl }
     }
   }
   ```

Trate `uploadUrl` como uma credencial de escrita de curta duração e não a registre em logs nem a exponha. `accessUrl` é a URL de mídia usada ao criar a publicação.

Você também pode continuar usando os [endpoints REST de upload](/docs/apis/media/upload-media) e referenciar as URLs resultantes a partir do GraphQL. As duas interfaces compartilham a mesma biblioteca de mídia.

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

<ul class="custom-bullets">
  <li>[Erros](/docs/apis/graphql/errors) — códigos de status HTTP, formatos de erro e 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>