Eden Media API

openapi: 3.2.0
info:
  title: Eden workspace Media API
  version: 1.0.0
  summary: Every Eden MCP tool as a plain HTTPS call.
  description: 'Each tool in Eden''s MCP server (`https://mcp.eden.so/mcp`) also runs as `POST /v1/tools/` with its arguments as the JSON body: Discover search, creator analysis, the ads library, scheduling, analytics, boards, notes, tables, Custom AIs, and the store.


    **Sign in:** `Authorization: Bearer `, an Eden API key from Settings → API (`eden_pat_…`) or an OAuth access token. Read-only keys can''t run write tools, and a Custom key only sees the tools its access allows.


    **Credits and limits:** the same as MCP. Research tools cost 0.1 to 0.5 AI credits a call; saving, scheduling, and reading your own workspace are free. 120 calls a minute per key, shared with MCP.


    **Answers:** the tool''s own `{ ok: true, ... }` or `{ ok: false, status, message }`, with the HTTP status mirroring `status`.


    Invite-only tools are left out of this file; `GET /v1/tools` lists what a key can use. The store API (sales, customers, products, webhooks) is a separate spec: https://api.eden.so/store-app/v1/openapi.json'
  contact:
    name: Eden
    url: https://eden.so/help/api/use-the-eden-api/
  termsOfService: https://eden.so/terms/
servers:
- url: https://mcp.eden.so
  description: Eden workspace API
security:
- apiKey: []
tags:
- name: Media
paths:
  /v1/tools/eden_study_top_carousels:
    post:
      operationId: eden_study_top_carousels
      summary: Study top carousels
      description: 'Research top-performing Instagram carousel posts and return a slide-by-slide teardown (structure, hook, per-slide text, design patterns) as reusable pattern notes. Study ONE creator''s carousels (pass `creator`) OR a niche across creators (pass `niche`, optionally `scope: "following"` to stay inside the user''s follows) — pass one or the other, not both. Billed research; vision analysis can take ~30s+. This does NOT generate carousel media — Eden exposes no AI media generation over MCP (image and carousel creation happen inside the Eden app).'
      tags:
      - Media
      x-read-only: true
      x-destructive: false
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                workspaceId:
                  description: Workspace id (eden_list_workspaces). Omit for the default.
                  type: string
                  minLength: 1
                creator:
                  description: Creator handle/name/profile URL to study. Omit to study a niche.
                  type: string
                  minLength: 1
                niche:
                  description: Topic/niche to study across creators when no creator is given.
                  type: string
                  minLength: 1
                  maxLength: 80
                scope:
                  description: Use `following` to restrict niche search to creators the user follows.
                  type: string
                  enum:
                  - global
                  - following
                minOutlierScore:
                  description: Optional minimum outlier score.
                  type: number
                  minimum: 0
                limit:
                  description: How many carousel posts to study. Default 8.
                  type: integer
                  minimum: 3
                  maximum: 12
      responses:
        '200':
          description: 'The tool''s result: `{ ok: true, ... }`. Tools that answer plain text come back as `{ ok: true, text }`.'
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/Failure'
        '401':
          $ref: '#/components/responses/Failure'
        '402':
          $ref: '#/components/responses/Failure'
        '403':
          $ref: '#/components/responses/Failure'
        '404':
          $ref: '#/components/responses/Failure'
        '409':
          $ref: '#/components/responses/Failure'
        '422':
          $ref: '#/components/responses/Failure'
        '429':
          $ref: '#/components/responses/Failure'
        '500':
          $ref: '#/components/responses/Failure'
        '503':
          $ref: '#/components/responses/Failure'
components:
  schemas:
    Failure:
      type: object
      required:
      - ok
      - status
      - message
      properties:
        ok:
          type: boolean
          const: false
        status:
          type: string
          description: auth-expired (401), upgrade-required (402), forbidden / not-enabled (403), not-found (404), conflict (409), invalid / needs-input / missing-workspace / confirmation-required (422), quota-exceeded / rate-limited (429), unreachable / unavailable (503), error (500).
        message:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              message:
                type: string
        outOfCredits:
          type: boolean
        upgradeUrl:
          type: string
  responses:
    Failure:
      description: The call failed. `status` and `message` say why and what to do.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Failure'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: eden_pat_…
      description: An Eden API key from Settings → API, or an OAuth access token.