​
Qué necesitas

Antes de enviar peticiones, necesitas:

  1. Una API key de Ocoya
  2. Un ID de brand
  3. IDs de social profile si quieres crear o programar posts

​
Consigue una API Key

Crea o copia una API key desde tu configuración de Ocoya API.

Create API key

Las API keys son para uso en el servidor. No las expongas en JavaScript del navegador, apps móviles ni repositorios públicos.

​
Base URL

Todos los ejemplos de la REST API usan:

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

​
Envía tu primera petición

La forma más rápida de comprobar que tu API key funciona es llamar a /me.

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

Si la clave es válida, la API devuelve tu contexto de usuario.

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

​
Flujo típico de publicación

1

List brands

Llama a GET /brands y elige la brand desde la que quieres publicar.

2

Connect social profiles

Si la brand aún no tiene perfiles conectados, llama a POST /social-profiles/connection-url y abre la url devuelta en un navegador.

3

List social profiles

Llama a GET /social-profiles?brandId=BRAND_ID para encontrar los IDs de perfiles conectados.

4

Resolve optional context

Llama a GET /hashtag-libraries?brandId=BRAND_ID cuando un borrador con IA deba usar contexto de hashtags guardado.

5

Create a draft or scheduled post

Llama a POST /post?brandId=BRAND_ID con un caption, URLs de medios, IDs de social profile de destino y scheduledAt opcional.

6

Create an AI draft

Llama a POST /post/ai?brandId=BRAND_ID con un prompt cuando quieras que Ocoya genere primero el caption.

7

Create an AI campaign

Llama a POST /campaigns?brandId=BRAND_ID para poner en cola la generación de una campaña con varios posts y recibir una respuesta inmediata GENERATING.

8

Manage posts

Usa GET /post, PATCH /post/{postId} y DELETE /post/{postId} para revisar, reprogramar o eliminar posts.

​
Create A Post

Usa scheduledAt cuando quieras un post programado. Omítelo cuando quieras un borrador.

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

​
Connect A Social Profile

Usa POST /social-profiles/connection-url cuando necesites una URL de navegador para conectar un nuevo social profile.

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

Abre la url devuelta mientras estás conectado a Ocoya.

​
Create An AI Draft

Usa POST /post/ai cuando quieras que Ocoya genere el caption a partir de un prompt antes de crear el borrador.

Usa hashtagLibraryId y referenceDesignIds cuando quieras que el borrador use una hashtag library guardada o el contexto de una plantilla de 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"]
  }'

​
Create An AI Campaign

Usa POST /campaigns cuando quieras que Ocoya genere en segundo plano una campaña con varios posts.

La respuesta se devuelve de inmediato con estado GENERATING. Usa hashtagLibraryId cuando la campaña deba usar una hashtag library 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

Usa la REST API para sistemas backend que ya saben exactamente lo que necesitan hacer.

Usa MCP cuando quieras que clientes de IA como Claude, Codex o ChatGPT descubran y llamen a herramientas de Ocoya después de que el usuario apruebe el acceso por OAuth.