​
O que você precisa

Antes de enviar pedidos, você precisa de:

  1. Uma chave de API da Ocoya
  2. Um ID de brand
  3. IDs de perfis sociais se quiser criar ou agendar publicações

​
Obter uma API key

Crie ou copie uma API key nas definições de API da sua conta Ocoya.

Create API key

As API keys são para utilização do lado do servidor. Não as exponha em JavaScript no navegador, em apps móveis ou em repositórios públicos.

​
Base URL

Todos os exemplos da REST API usam:

https://www.app.ocoya.com/api/_public/v1

​
Enviar o seu primeiro pedido

A forma mais rápida de verificar se a sua API key está a funcionar é chamar /me.

curl -X GET "https://www.app.ocoya.com/api/_public/v1/me" \
  -H "X-API-Key: YOUR_API_KEY"

Se a chave for válida, a API devolve o contexto do seu utilizador.

{
  "id": "clx354swx0006ghoatnjknv98",
  "name": "Ocoya Support",
  "email": "support@ocoya.com"
}

​
Fluxo típico de publicação

1

List brands

Chame GET /brands e escolha a brand a partir da qual quer publicar.

2

Connect social profiles

Se a brand ainda não tiver perfis ligados, chame POST /social-profiles/connection-url e abra o url devolvido num navegador.

3

List social profiles

Chame GET /social-profiles?brandId=BRAND_ID para encontrar os IDs dos perfis ligados.

4

Resolve optional context

Chame GET /hashtag-libraries?brandId=BRAND_ID quando um rascunho de IA deve usar contexto de hashtags guardado.

5

Create a draft or scheduled post

Chame POST /post?brandId=BRAND_ID com uma legenda, URLs de media, IDs dos perfis sociais de destino e scheduledAt opcional.

6

Create an AI draft

Chame POST /post/ai?brandId=BRAND_ID com um prompt quando quiser que a Ocoya gere primeiro a legenda.

7

Create an AI campaign

Chame POST /campaigns?brandId=BRAND_ID para colocar em fila a geração de uma campanha com múltiplas publicações e receber imediatamente uma resposta GENERATING.

8

Manage posts

Use GET /post, PATCH /post/{postId} e DELETE /post/{postId} para inspecionar, reagendar ou remover publicações.

​
Criar uma publicação

Use scheduledAt quando quiser uma publicação agendada. Omita-o quando quiser um rascunho.

curl -X POST "https://www.app.ocoya.com/api/_public/v1/post?brandId=BRAND_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Launching our summer campaign today.",
    "mediaUrls": ["https://example.com/image.jpg"],
    "socialProfileIds": ["SOCIAL_PROFILE_ID"],
    "scheduledAt": "2026-07-01T09:00:00Z"
  }'

​
Ligar um perfil social

Use POST /social-profiles/connection-url quando precisar de um URL de navegador para ligar um novo perfil social.

curl -X POST "https://www.app.ocoya.com/api/_public/v1/social-profiles/connection-url?brandId=BRAND_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"instagram"}'

Abra o url devolvido enquanto tem sessão iniciada na Ocoya.

​
Criar um rascunho com IA

Use POST /post/ai quando quiser que a Ocoya gere a legenda a partir de um prompt antes de criar o rascunho.

Use hashtagLibraryId e referenceDesignIds quando quiser que o rascunho utilize uma biblioteca de hashtags guardada ou o contexto de um template do Studio.

curl -X POST "https://www.app.ocoya.com/api/_public/v1/post/ai?brandId=BRAND_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Write a friendly launch post for our new analytics dashboard.",
    "tone": "friendly",
    "postLength": "medium",
    "socialProfileIds": ["SOCIAL_PROFILE_ID"],
    "hashtagLibraryId": "HASHTAG_LIBRARY_ID",
    "generateImage": true,
    "referenceUrls": ["https://example.com/reference.png"],
    "referenceDesignIds": ["STUDIO_DESIGN_ID"]
  }'

​
Criar uma campanha com IA

Use POST /campaigns quando quiser que a Ocoya gere, em segundo plano, uma campanha com múltiplas publicações.

A resposta é devolvida imediatamente com o estado GENERATING. Use hashtagLibraryId quando a campanha deva utilizar uma biblioteca de hashtags guardada.

curl -X POST "https://www.app.ocoya.com/api/_public/v1/campaigns?brandId=BRAND_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Summer launch campaign for our ecommerce analytics dashboard, aimed at marketing teams already using spreadsheets. Confident, practical tone.",
    "goal": "launch",
    "duration": 10,
    "count": 6,
    "postLength": "medium",
    "hashtagLibraryId": "HASHTAG_LIBRARY_ID",
    "socialProfileIds": ["SOCIAL_PROFILE_ID"],
    "generateMedia": true
  }'

​
MCP vs REST API

Use a REST API para sistemas de backend que já sabem exatamente o que precisam de fazer.

Use MCP quando quiser que clientes de IA como Claude, Codex ou ChatGPT descubram e chamem ferramentas da Ocoya depois de o utilizador aprovar o acesso por OAuth.