# Publique nas redes

> Poste um ou vários clipes editados em várias contas de uma vez, agora ou agendado, e acompanhe cada publicação.

Um **post** publica edições em contas conectadas. Cada par edição e conta vira um **item**, com estado próprio: num post para TikTok e YouTube, um item pode sair e o outro falhar.

Você não precisa renderizar antes. O post renderiza o que falta e publica.

## Escolha as contas

```bash
curl https://api.cut.pro/api/v1/connections \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

Cada conexão traz `id`, `platform`, `username` e números da audiência. O `id` é o `connection_id` do post. Se a conta que a pessoa quer não está na lista, peça o link de conexão e entregue para ela:

```bash
curl "https://api.cut.pro/api/v1/connections/link?platform=tiktok" \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

A conexão é feita por quem é dono da conta, no navegador. Quando ela voltar, liste de novo.

## Crie o post

```bash
curl -X POST https://api.cut.pro/api/v1/posts \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "videos": [
      {
        "edit_id": "7412910087700001",
        "targets": [
          {
            "connection_id": "7390012299881100",
            "metadata": { "tiktok": { "title": "O refrão que todo mundo sabe #musica", "privacyLevel": "PUBLIC_TO_EVERYONE" } }
          },
          {
            "connection_id": "7390012299881200",
            "metadata": { "youtube": { "title": "O refrão que todo mundo sabe", "categoryId": "10", "privacyStatus": "public" } }
          }
        ]
      }
    ],
    "scheduled_at": "2026-10-30T12:00:00.000Z"
  }'
```

```json title="201 Created"
{ "id": "7412930011223344", "item_count": 2, "scheduled_at": "2026-10-30T12:00:00.000Z", "status": "pending" }
```

- `edit_id` vem do clipe, do render ou de um [vídeo gerado](/generations). Vários `videos` num post só publicam vários clipes de uma vez.
- `scheduled_at` agenda, em ISO 8601 no futuro. Sem ele, publica agora.

## Metadata por rede

`metadata` leva uma chave com o nome da rede e, dentro, os campos da própria rede, com os nomes dela (`privacyLevel`, `categoryId`). É a única parte da API fora de `snake_case`: o conteúdo segue para a rede como está.

| Rede | Obrigatórios | Outros campos |
|---|---|---|
| `youtube` | `title`, `categoryId`, `privacyStatus` | `description`, `tags`, `madeForKids`, `notifySubscribers`, `license`, `embeddable` |
| `tiktok` | `title`, `privacyLevel` | `disableDuet`, `disableComment`, `disableStitch`, `brandContentToggle`, `brandOrganicToggle`, `isAigc` |
| `instagram` | | `caption`, `shareToFeed`, `collaborators`, `userTags`, `audioName`, `thumbOffset`, `trialReel`, `firstComment` |
| `facebook` | | `description`, `postType` (`reel` ou `feed`), `videoTitle`, `link`, `firstComment` |
| `threads` | | `text`, `replyControl`, `firstComment` |
| `twitter` | | `text`, `replySettings` |
| `linkedin` | `text` | `visibility` |
| `pinterest` | `boardId`, `title`, `description` | `link`, `coverImageUrl` |
| `bluesky` | | `text`, `languages` |

Todas aceitam `coverImageId` para a capa. Os limites de cada campo, e as demais redes, estão em [`POST /posts`](/reference). Uma rede que ainda está chegando recusa o pedido inteiro com `400 PLATFORM_UNAVAILABLE`, antes de criar qualquer coisa.

## Acompanhe

```bash
curl https://api.cut.pro/api/v1/posts/7412930011223344 \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

Cada item passa por `pending` → `rendering` → `publishing` → `completed` ou `failed`. No `completed`, `published_url` é o link do vídeo na rede. No `failed`, `error_code` diz o motivo.

O post resume os itens:

| `status` do post | Significa |
|---|---|
| `pending` | Agendado ou esperando começar. |
| `processing` | Itens renderizando ou publicando. |
| `completed` | Todos os itens publicados. |
| `partial` | Uma parte publicou, outra falhou. Trate como aviso, não como sucesso. |
| `failed` | Nenhum item publicou. |
| `cancelled` | Cancelado. |

Consulte a cada 10 a 30 segundos. Um item que falhou volta para a fila com:

```bash
curl -X POST https://api.cut.pro/api/v1/posts/7412930011223344/items/7412930011223401/retry \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

## Mude, adiante ou cancele

| Rota | O que faz |
|---|---|
| `PATCH /posts/{id}` | Muda `scheduled_at` (no mínimo 1 minuto à frente, ou `null` para publicar já) enquanto todo item está `pending`. Com `items`, troca o conjunto de itens pendentes: com `item_id` atualiza, sem insere, ausente apaga. Itens publicados não mudam. |
| `POST /posts/{id}/publish` | Publica agora um post agendado, ou destrava um que ficou parado. |
| `DELETE /posts/{id}` | Cancela todos os itens que ainda não saíram. O que já está no ar continua no ar. |
| `DELETE /posts/{id}/items/{itemId}` | Cancela um item `pending`, `rendering` ou `failed`. Num item `completed`, apaga o vídeo da rede, nas redes que permitem. Item em `publishing` não dá mais para parar. |

> Apagar um item publicado tira o vídeo da conta da pessoa na rede. Se a rede recusa, a resposta é `400` com o motivo (`DELETE_NOT_SUPPORTED`, `PERMISSION_MISSING`, `DELETE_LIMIT_REACHED`) e nada muda.

## Erros

| Code | Quando |
|---|---|
| `INVALID_METADATA` | Um campo da rede está errado ou falta. `extra.field` e `extra.platform` dizem qual. |
| `INVALID_CONNECTIONS` | Conexão inexistente ou desconectada. `extra.invalid_connections` lista quais. Peça para reconectar com `GET /connections/link`. |
| `EDITS_NOT_FOUND` | Edição que não é deste workspace, em `extra.invalid_edits`. |
| `DAILY_LIMIT_EXCEEDED` | A conta passou do limite diário de posts da rede. `extra` traz `daily_limit`, `used_today` e a conexão. |
| `DUPLICATE_POST` | O mesmo pedido (mesmas edições, contas e horário) chegou de novo logo depois do primeiro. O primeiro vale: não repita. |
| `MEDIA_REFUNDED` | A edição é de um vídeo gerado com IA que foi reembolsado. |
| `RECORDING_EXPIRED` | A edição é de um clipe de live cuja gravação expirou. |
| `INVALID_SCHEDULED_AT` | Horário no passado ou fora do formato ISO 8601. |