> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ocoya.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to use

> Make your first Ocoya REST API request.

## What You Need

Before you send requests, you need:

1. An Ocoya API key
2. A workspace ID
3. Social profile IDs if you want to create or schedule posts

## Get An API Key

Create or copy an API key from your Ocoya API settings.

[Create API key](https://app.ocoya.com/general/settings/api)

<Warning>
  API keys are for server-side usage. Do not expose them in browser JavaScript, mobile apps, or public repositories.
</Warning>

## Base URL

All REST API examples use:

```txt theme={null}
https://app.ocoya.com/api/_public/v1
```

## Send Your First Request

The fastest way to verify your API key is working is to call `/me`.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.ocoya.com/api/_public/v1/me" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```js Node.js theme={null}
  const response = await fetch('https://app.ocoya.com/api/_public/v1/me', {
    method: 'GET',
    headers: {
      'Accept': 'application/json',
      'X-API-Key': process.env.OCOYA_API_KEY,
    },
  })

  const me = await response.json()
  console.log(me)
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.get(
      "https://app.ocoya.com/api/_public/v1/me",
      headers={"X-API-Key": os.environ["OCOYA_API_KEY"]},
  )

  print(response.json())
  ```
</CodeGroup>

If the key is valid, the API returns your user context.

```json theme={null}
{
  "id": "clx354swx0006ghoatnjknv98",
  "name": "Ocoya Support",
  "email": "support@ocoya.com"
}
```

## Typical Publishing Flow

<Steps>
  <Step title="List workspaces">
    Call `GET /workspaces` and choose the workspace you want to publish from.
  </Step>

  <Step title="Connect social profiles">
    If the workspace has no connected profiles yet, call `GET /social-profiles/connection-url` and open the returned `authUrl` in a browser.
  </Step>

  <Step title="List social profiles">
    Call `GET /social-profiles?workspaceId=WORKSPACE_ID` to find connected profile IDs.
  </Step>

  <Step title="Resolve optional context">
    Call `GET /brand-kits?workspaceId=WORKSPACE_ID` and `GET /hashtag-libraries?workspaceId=WORKSPACE_ID` when an AI draft should use saved brand or hashtag context.
  </Step>

  <Step title="Create a draft or scheduled post">
    Call `POST /post?workspaceId=WORKSPACE_ID` with a caption, media URLs, target social profile IDs, and optional `scheduledAt`.
  </Step>

  <Step title="Create an AI draft">
    Call `POST /post/ai?workspaceId=WORKSPACE_ID` with a prompt when you want Ocoya to generate the caption first.
  </Step>

  <Step title="Manage posts">
    Use `GET /post`, `PATCH /post/{postId}`, and `DELETE /post/{postId}` to inspect, reschedule, or remove posts.
  </Step>
</Steps>

## Create A Post

Use `scheduledAt` when you want a scheduled post. Omit it when you want a draft.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://app.ocoya.com/api/_public/v1/post?workspaceId=WORKSPACE_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"
    }'
  ```

  ```js Node.js theme={null}
  const response = await fetch('https://app.ocoya.com/api/_public/v1/post?workspaceId=WORKSPACE_ID', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.OCOYA_API_KEY,
    },
    body: JSON.stringify({
      caption: 'Launching our summer campaign today.',
      mediaUrls: ['https://example.com/image.jpg'],
      socialProfileIds: ['SOCIAL_PROFILE_ID'],
      scheduledAt: '2026-07-01T09:00:00Z',
    }),
  })

  const post = await response.json()
  console.log(post)
  ```
</CodeGroup>

## Connect A Social Profile

Use `GET /social-profiles/connection-url` when you need a browser URL for connecting a new social profile.

```bash cURL theme={null}
curl -X GET "https://app.ocoya.com/api/_public/v1/social-profiles/connection-url?workspaceId=WORKSPACE_ID&provider=instagram" \
  -H "X-API-Key: YOUR_API_KEY"
```

Open the returned `authUrl` while signed in to Ocoya. Instagram returns a Facebook OAuth URL first because Instagram Business profiles are connected through Facebook Pages.

## Create An AI Draft

Use `POST /post/ai` when you want Ocoya to generate the caption from a prompt before creating the draft.

Use `brandId`, `hashtagLibraryId`, and `referenceDesignIds` when you want the draft to use saved brand kit, hashtag library, or Studio template context.

```bash cURL theme={null}
curl -X POST "https://app.ocoya.com/api/_public/v1/post/ai?workspaceId=WORKSPACE_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",
    "length": "medium",
    "socialProfileIds": ["SOCIAL_PROFILE_ID"],
    "brandId": "BRAND_KIT_ID",
    "hashtagLibraryId": "HASHTAG_LIBRARY_ID",
    "generateImage": true,
    "referenceUrls": ["https://example.com/reference.png"],
    "referenceDesignIds": ["STUDIO_DESIGN_ID"]
  }'
```

## MCP vs REST API

Use the REST API for backend systems that already know exactly what they need to do.

Use [MCP](/mcp/get-started) when you want AI clients such as Claude, Codex, or ChatGPT to discover and call Ocoya tools after the user approves OAuth access.