​
Di cosa hai bisogno

Prima di inviare richieste, ti servono:

  1. Una API key di Ocoya
  2. Un brand ID
  3. Degli ID dei profili social se vuoi creare o programmare post

​
Ottieni una API key

Crea o copia una API key dalle impostazioni API del tuo account Ocoya.

Create API key

Le API key sono pensate per l’uso lato server. Non esporle in JavaScript nel browser, nelle app mobile o in repository pubblici.

​
Base URL

Tutti gli esempi della REST API usano:

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

​
Invia la tua prima richiesta

Il modo più veloce per verificare che la tua API key funzioni è chiamare /me.

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

Se la key è valida, l’API restituisce il tuo contesto utente.

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

​
Flusso tipico di pubblicazione

1

List brands

Chiama GET /brands e scegli il brand da cui vuoi pubblicare.

2

Connect social profiles

Se il brand non ha ancora profili connessi, chiama POST /social-profiles/connection-url e apri la url restituita in un browser.

3

List social profiles

Chiama GET /social-profiles?brandId=BRAND_ID per trovare gli ID dei profili connessi.

4

Resolve optional context

Chiama GET /hashtag-libraries?brandId=BRAND_ID quando un draft AI deve usare il contesto degli hashtag salvati.

5

Create a draft or scheduled post

Chiama POST /post?brandId=BRAND_ID con una caption, gli URL dei media, gli ID dei profili social di destinazione e un scheduledAt opzionale.

6

Create an AI draft

Chiama POST /post/ai?brandId=BRAND_ID con un prompt quando vuoi che Ocoya generi prima la caption.

7

Create an AI campaign

Chiama POST /campaigns?brandId=BRAND_ID per mettere in coda la generazione di una campagna multi-post e ricevere subito una risposta GENERATING.

8

Manage posts

Usa GET /post, PATCH /post/{postId} e DELETE /post/{postId} per ispezionare, riprogrammare o rimuovere i post.

​
Crea un post

Usa scheduledAt quando vuoi un post programmato. Omettilo quando vuoi un draft.

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"
  }'

​
Connetti un profilo social

Usa POST /social-profiles/connection-url quando ti serve un URL da aprire nel browser per connettere un nuovo profilo 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"}'

Apri la url restituita mentre sei connesso a Ocoya.

​
Crea un AI draft

Usa POST /post/ai quando vuoi che Ocoya generi la caption partendo da un prompt prima di creare il draft.

Usa hashtagLibraryId e referenceDesignIds quando vuoi che il draft usi il contesto di una hashtag library salvata o di un template di 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"]
  }'

​
Crea una AI campaign

Usa POST /campaigns quando vuoi che Ocoya generi in background una campagna composta da più post.

La risposta arriva subito con lo stato GENERATING. Usa hashtagLibraryId quando la campagna deve usare una hashtag library salvata.

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

Usa la REST API per i sistemi backend che sanno già esattamente cosa devono fare.

Usa MCP quando vuoi che client AI come Claude, Codex o ChatGPT possano scoprire e chiamare gli strumenti di Ocoya dopo che l’utente ha approvato l’accesso OAuth.