Supergrow API Documentation

openapi: 3.0.3
info:
  title: Supergrow External API
  description: |
    The Supergrow External API allows you to programmatically manage workspaces, posts, content, and analytics for your LinkedIn content management workflow.

## Authentication
    All API requests require an API key passed in the `X-Api-Key` header.

### Getting an API Key
    To obtain an API key, please send an email to support@supergrow.ai with your request. Our team will respond with your unique API key and any additional information needed to get started.

## Rate Limits
    - **3,600 requests per hour** per user
    - **5,000 requests per day** per user
    - **Content extraction:** 10 extractions per day per workspace

## MCP Server
    Supergrow offers an MCP (Model Context Protocol) server that lets you manage your LinkedIn content directly from AI tools like Claude. Contact support@supergrow.ai to learn more.

version: "1.0.0"
  contact:
    url: https://help.supergrow.ai
servers:
  - url: https://external-api.supergrow.ai/api/v1/external
    description: Production
security:
  - ApiKeyAuth: []

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key

schemas:
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
        error_code:
          type: string
          nullable: true
          description: Machine-readable error code (e.g. PAID_PLAN_REQUIRED)

Workspace:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        is_archived:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        role:
          type: string
          enum: [ADMIN, TEAM MEMBER, CLIENT, ORG_OWNER, ORG_ADMIN]
        timezone:
          type: string
          nullable: true
          description: Workspace timezone (e.g. "Asia/Kolkata"). Used for scheduling posts.
        language:
          type: string
          nullable: true
          description: Workspace content language (e.g. "English", "Hindi").

AutoPlugComment:
      type: object
      properties:
        id:
          type: string
          format: uuid
        post_id:
          type: string
          format: uuid
        text:
          type: string
        status:
          type: string
          enum: [draft, scheduled, published, failed]
        post_after_time_unit:
          type: string
          enum: [minutes, hours, days]
        post_after_time_unit_count:
          type: integer
        published_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time

CompanyPage:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        url:
          type: string
        logo_url:
          type: string
        page_id:
          type: string
          description: LinkedIn company page ID

Post:
      type: object
      properties:
        id:
          type: string
          format: uuid
        text:
          type: string
        image_urls:
          type: array
          items:
            type: string
        status:
          type: string
          enum: [draft, scheduled, published, failed, under_review, approved, needs_changes]
        published_at:
          type: string
          format: date-time
          nullable: true
        published_url:
          type: string
          nullable: true
        video_url:
          type: string
          nullable: true
        video_title:
          type: string
          nullable: true
        carousel_title:
          type: string
          nullable: true
        file_url:
          type: string
          nullable: true
        publish_from_type:
          type: string
          enum: [personal, company]
          description: Whether the post is published from a personal profile or company page
        linked_in_company_page_id:
          type: string
          format: uuid
          nullable: true
          description: The company page ID if publish_from_type is "company"
        likes_count:
          type: integer
          nullable: true
        comments_count:
          type: integer
          nullable: true
        reshares_count:
          type: integer
          nullable: true
        impressions_count:
          type: integer
          nullable: true
        app_url:
          type: string
          nullable: true
          description: URL to edit the post in the Supergrow app
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

ContentDna:
      type: object
      nullable: true
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum: [analyzing, completed, failed]
        linkedin_profile_url:
          type: string
        name:
          type: string
        current_role:
          type: string
        company:
          type: string
        industry:
          type: string
        experience_years:
          type: integer
        seniority_level:
          type: string
        expertise_areas:
          type: array
          items:
            type: string
        main_topics:
          type: array
          items:
            type: string
        target_customers:
          type: array
          items:
            type: object
        content_positioning:
          type: object
        writing_style:
          type: object
        content_patterns:
          type: object
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

LinkedInAccount:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        avatar_url:
          type: string
          nullable: true
        linked_in_profile_url:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

WeeklyReport:
      type: object
      properties:
        id:
          type: string
          format: uuid
        week_start_date:
          type: string
          format: date
        week_end_date:
          type: string
          format: date
        week_label:
          type: string
        status:
          type: string
        summary:
          type: object
          properties:
            posts_published:
              type: integer
            total_engagements:
              type: integer
            total_impressions:
              type: integer
            rolling_average_engagement:
              type: number
            vs_baseline_percentage:
              type: number
            vs_baseline_text:
              type: string
        best_performer:
          type: object
          nullable: true
          properties:
            post_id:
              type: string
            multiplier:
              type: number
            insight:
              type: object
        worst_performer:
          type: object
          nullable: true
          properties:
            post_id:
              type: string
            multiplier:
              type: number
            insight:
              type: object
        posts_breakdown:
          type: array
          items:
            type: object
        audience_growth:
          type: object
          nullable: true
        created_at:
          type: string
          format: date-time

DailyAnalytic:
      type: object
      properties:
        date:
          type: string
          format: date
        impressions:
          type: integer
        engagements:
          type: integer
        reactions:
          type: integer
        comments:
          type: integer
        reshares:
          type: integer
        members_reached:
          type: integer

ExtractionResult:
      type: object
      properties:
        text:
          type: string
        url:
          type: string

KnowledgeBaseItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        description:
          type: string
          nullable: true
        source_type:
          type: string
          enum: [text, website, pdf, document, youtube, voice]
        source_url:
          type: string
          nullable: true
        status:
          type: string
          enum: [draft, processing, ready, failed]
        scope:
          type: string
          enum: [workspace, org]
        chunks_count:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

KnowledgeBaseSearchResultItem:
      type: object
      properties:
        score:
          type: number
          format: float
          description: Relevance score (0–1, higher is better)
        entry_type:
          type: string
          enum: [chunk, insight, chunk_with_insight]
        chunk:
          type: object
          nullable: true
          description: The source text chunk (present for chunk and chunk_with_insight entries)
          properties:
            id:
              type: string
            content:
              type: string
            content_preview:
              type: string
            chunk_index:
              type: integer
            token_count:
              type: integer
        insight:
          type: object
          nullable: true
          description: Extracted insight (present for insight and chunk_with_insight entries)
          properties:
            type:
              type: string
              enum: [statistic, quote, milestone, product_feature, customer_proof_point, contrarian_claim]
            text:
              type: string
            confidence:
              type: string
              enum: [high, medium, low]
        knowledge_base_item:
          type: object
          properties:
            id:
              type: string
              format: uuid
            title:
              type: string
            description:
              type: string
              nullable: true
            source_type:
              type: string
            source_url:
              type: string
              nullable: true
        metadata:
          type: object
          description: Additional metadata for the search result item.

Pagination:
      type: object
      properties:
        total:
          type: integer
        page:
          type: integer
        per_page:
          type: integer
        pages:
          type: integer

parameters:
    WorkspaceId:
      name: workspace_id
      in: query
      required: true
      schema:
        type: string
        format: uuid
      description: The ID of the workspace

paths:
  /workspaces:
    get:
      summary: List all workspaces
      description: Returns all workspaces accessible to the authenticated user, including their role in each.
      tags: [Workspaces]
      responses:
        "200":
          description: List of workspaces
          content:
            application/json:
              schema:
                type: object
                properties:
                  workspaces:
                    type: array
                    items:
                      $ref: "#/components/schemas/Workspace"

/posts:
    get:
      summary: List posts
      description: Lists posts in a workspace filtered by status.
      tags: [Posts]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: status
          in: query
          required: true
          schema:
            type: string
            enum: [draft, scheduled, published, failed, all]
        - name: tag_ids
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated tag IDs
      responses:
        "200":
          description: List of posts
          content:
            application/json:
              schema:
                type: object
                properties:
                  posts:
                    type: array
                    items:
                      $ref: "#/components/schemas/Post"
    post:
      summary: Create a post
      description: |
        Creates a new draft post in a workspace. Optionally publish from a company page by providing `linked_in_company_page_id`.
        Use `GET /company-pages` to list available company pages.
      tags: [Posts]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text:
                  type: string
                  maxLength: 3000
                image_urls:
                  type: array
                  items:
                    type: string
                file_url:
                  type: string
                carousel_title:
                  type: string
                video_url:
                  type: string
                video_title:
                  type: string
                video_thumbnail_url:
                  type: string
                linked_in_company_page_id:
                  type: string
                  format: uuid
                  description: Optional. If provided, the post will be published from this company page instead of the personal profile. Use GET /company-pages to list available pages.
      responses:
        "201":
          description: Post created
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  post:
                    $ref: "#/components/schemas/Post"

/posts/{id}:
    get:
      summary: Get a post
      description: Get details for a specific post.
      tags: [Posts]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Post details
          content:
            application/json:
              schema:
                type: object
                properties:
                  post:
                    $ref: "#/components/schemas/Post"
    put:
      summary: Update a post
      description: Updates an existing draft post.
      tags: [Posts]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text:
                  type: string
                  maxLength: 3000
                image_urls:
                  type: array
                  items:
                    type: string
                file_url:
                  type: string
                carousel_title:
                  type: string
                video_url:
                  type: string
                video_title:
                  type: string
                video_thumbnail_url:
                  type: string
      responses:
        "200":
          description: Post updated
    delete:
      summary: Delete a post
      description: Deletes a draft or failed post.
      tags: [Posts]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Post deleted

/posts/{id}/schedule:
    post:
      summary: Schedule a post
      description: >-
        Schedules a post for publication at a specific time.
        Pass `hour` in the workspace's local timezone (NOT UTC).
        For example, for 2 PM IST pass hour=14.
      tags: [Posts]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                day_of_week:
                  type: integer
                  description: Day of week (0=Sunday, 1=Monday, ..., 6=Saturday)
                hour:
                  type: integer
                  minimum: 0
                  maximum: 23
                  description: Hour in the workspace's local timezone (0-23). Do NOT convert to UTC.
                minute:
                  type: integer
                  minimum: 0
                  maximum: 59
                day_of_the_month:
                  type: integer
                  minimum: 1
                  maximum: 31
                month:
                  type: integer
                  minimum: 1
                  maximum: 12
                year:
                  type: integer
      responses:
        "200":
          description: Post scheduled

/posts/{id}/unschedule:
    post:
      summary: Unschedule a post
      description: Removes scheduling and reverts post to draft.
      tags: [Posts]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Post unscheduled

/posts/{id}/publish:
    post:
      summary: Publish a post
      description: Immediately initiates the publishing process (asynchronous).
      tags: [Posts]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Publishing initiated

/posts/queue:
    post:
      summary: Queue a post
      description: |
        Creates a post and auto-schedules it in the next available time slot.
        Optionally publish from a company page by providing `linked_in_company_page_id`.
      tags: [Posts]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text:
                  type: string
                  maxLength: 3000
                image_urls:
                  type: array
                  items:
                    type: string
                file_url:
                  type: string
                carousel_title:
                  type: string
                video_url:
                  type: string
                video_title:
                  type: string
                linked_in_company_page_id:
                  type: string
                  format: uuid
                  description: Optional. Publish from a company page instead of personal profile.
      responses:
        "201":
          description: Post created and scheduled

/posts/{id}/public-link:
    post:
      summary: Create public preview link
      description: Creates a public link to preview a post. Returns the existing link if one already exists.
      tags: [Posts]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Public link created
          content:
            application/json:
              schema:
                type: object
                properties:
                  public_url:
                    type: string
                    format: uri
        "404":
          description: Post not found
    delete:
      summary: Remove public preview link
      description: Removes the public preview link from a post.
      tags: [Posts]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Public link removed

/content-dna:
    get:
      summary: Get Content DNA
      description: Returns the Content DNA profile for the workspace — professional profile, writing style, content patterns, and target audience.
      tags: [Content DNA]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      responses:
        "200":
          description: Content DNA profile
          content:
            application/json:
              schema:
                type: object
                properties:
                  content_dna:
                    $ref: "#/components/schemas/ContentDna"

/content-dna/regenerate:
    post:
      summary: Regenerate Content DNA
      description: |
        Triggers Content DNA regeneration for the workspace. Uses the LinkedIn profile URL
        from the connected LinkedIn account. No request body needed.
      tags: [Content DNA]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      responses:
        "200":
          description: Regeneration started
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  content_dna:
                    $ref: "#/components/schemas/ContentDna"
        "422":
          description: No LinkedIn account connected or no profile URL
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

/linked-in-accounts:
    get:
      summary: Get LinkedIn accounts
      description: Returns LinkedIn accounts connected to the workspace. Sensitive tokens are never exposed.
      tags: [LinkedIn Accounts]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      responses:
        "200":
          description: List of LinkedIn accounts
          content:
            application/json:
              schema:
                type: object
                properties:
                  linked_in_accounts:
                    type: array
                    items:
                      $ref: "#/components/schemas/LinkedInAccount"

/calendar/weekly:
    get:
      summary: Get weekly calendar
      description: Returns the weekly calendar view with time slots and scheduled posts.
      tags: [Calendar]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          description: "Week offset (0=current, 1=next, -1=last)"
      responses:
        "200":
          description: Weekly calendar
          content:
            application/json:
              schema:
                type: object
                properties:
                  calendar:
                    type: object
                    description: Weekly calendar data with time slots and associated posts
                  timezone:
                    type: string
                    example: "America/New_York"
                    description: The workspace's configured timezone

/calendar/monthly:
    get:
      summary: Get monthly calendar
      description: Returns the monthly calendar view with time slots and scheduled posts.
      tags: [Calendar]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          description: "Month offset (0=current, 1=next, -1=last)"
      responses:
        "200":
          description: Monthly calendar
          content:
            application/json:
              schema:
                type: object
                properties:
                  calendar:
                    type: object
                    description: Monthly calendar data with time slots and associated posts
                  timezone:
                    type: string
                    example: "America/New_York"
                    description: The workspace's configured timezone

/kanban:
    get:
      summary: Get kanban board
      description: Returns the kanban board with posts grouped by status.
      tags: [Kanban]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            default: 10
            maximum: 100
      responses:
        "200":
          description: Kanban board

/kanban/column:
    get:
      summary: Get kanban column
      description: Returns posts for a single status column.
      tags: [Kanban]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: status
          in: query
          required: true
          schema:
            type: string
            enum: [draft, under_review, approved, needs_changes, scheduled, published]
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            default: 10
            maximum: 100
      responses:
        "200":
          description: Kanban column

/analytics/weekly-reports:
    get:
      summary: Get weekly reports
      description: Returns weekly content performance reports for the workspace.
      tags: [Analytics]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: limit
          in: query
          schema:
            type: integer
            default: 12
      responses:
        "200":
          description: List of weekly reports
          content:
            application/json:
              schema:
                type: object
                properties:
                  weekly_reports:
                    type: array
                    items:
                      $ref: "#/components/schemas/WeeklyReport"

/analytics/followers:
    get:
      summary: Get live followers data
      description: |
        Returns live follower count and trend data from LinkedIn API.
        Rate limited to 500 live analytics calls per day per workspace.
      tags: [Analytics]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: period
          in: query
          schema:
            type: string
            enum: [last_7_days, last_30_days, current_month, previous_month]
            default: last_7_days
          description: Predefined period (ignored if start_date/end_date provided)
        - name: start_date
          in: query
          schema:
            type: string
            format: date
          description: Custom start date (YYYY-MM-DD). Use with end_date.
        - name: end_date
          in: query
          schema:
            type: string
            format: date
          description: Custom end date (YYYY-MM-DD). Use with start_date.
      responses:
        "200":
          description: Followers data
          content:
            application/json:
              schema:
                type: object
                properties:
                  current_count:
                    type: integer
                  trend:
                    type: object
        "422":
          description: No LinkedIn account connected

/analytics/metrics:
    get:
      summary: Get live engagement metrics
      description: |
        Returns live engagement metric trends from LinkedIn API.
        Supported metrics: IMPRESSION, MEMBERS_REACHED, RESHARE, REACTION, COMMENT.
        Rate limited to 500 live analytics calls per day per workspace.
      tags: [Analytics]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: metric
          in: query
          schema:
            type: string
            enum: [IMPRESSION, MEMBERS_REACHED, RESHARE, REACTION, COMMENT]
            default: IMPRESSION
        - name: period
          in: query
          schema:
            type: string
            enum: [last_7_days, last_30_days, current_month, previous_month]
            default: last_7_days
          description: Predefined period (ignored if start_date/end_date provided)
        - name: start_date
          in: query
          schema:
            type: string
            format: date
          description: Custom start date (YYYY-MM-DD). Use with end_date.
        - name: end_date
          in: query
          schema:
            type: string
            format: date
          description: Custom end date (YYYY-MM-DD). Use with start_date.
      responses:
        "200":
          description: Metric trend data
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                  metric_type:
                    type: string
        "422":
          description: No LinkedIn account connected or invalid metric

/extract:
    post:
      summary: Extract text (auto-detect)
      description: Automatically detects URL type (webpage, YouTube, PDF, audio) and extracts text. Limited to 10 extractions per day per workspace.
      tags: [Content Extraction]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url:
                  type: string
                  format: uri
      responses:
        "200":
          description: Extracted text
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExtractionResult"
        "429":
          description: Daily extraction limit reached
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

/extract/youtube:
    post:
      summary: Extract YouTube transcript
      description: Extracts the transcript from a YouTube video. Limited to 10 extractions per day per workspace.
      tags: [Content Extraction]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url:
                  type: string
                  format: uri
      responses:
        "200":
          description: YouTube transcript
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExtractionResult"

/extract/pdf:
    post:
      summary: Extract PDF text
      description: Extracts text content from a PDF file. Limited to 10 extractions per day per workspace.
      tags: [Content Extraction]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url:
                  type: string
                  format: uri
      responses:
        "200":
          description: PDF text
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExtractionResult"

/extract/audio:
    post:
      summary: Transcribe audio
      description: |
        Transcribes audio or video files to text. Limited to 10 extractions per day per workspace.
        Supported formats: mp3, mp4, wav, m4a, aac, ogg, flac, wma, avi, mov, wmv, flv, webm, mkv.
      tags: [Content Extraction]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url:
                  type: string
                  format: uri
      responses:
        "200":
          description: Transcribed text
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExtractionResult"

/questions/from-topic:
    post:
      summary: Generate questions from a topic
      description: |
        Generates 8-12 interview-style questions for a given topic. Questions are personalized
        using the workspace's Content DNA (if available) and designed to extract insights
        for LinkedIn content creation. Each question includes follow-up prompts.
      tags: [Questions]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [topic]
              properties:
                topic:
                  type: string
                  description: The topic to generate questions about
      responses:
        "200":
          description: Generated questions
          content:
            application/json:
              schema:
                type: object
                properties:
                  questions:
                    type: array
                    items:
                      type: object
                      properties:
                        question:
                          type: string
                        follow_ups:
                          type: array
                          items:
                            type: string
        "422":
          description: Missing topic or generation failed

/questions/from-text:
    post:
      summary: Generate questions from text content
      description: |
        Analyzes text content (article, blog post, transcript, etc.) and generates
        interview-style questions to help extract insights for LinkedIn posts.
        Questions are self-contained with context from the text.
      tags: [Questions]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text:
                  type: string
                  description: The text content to analyze and generate questions from
      responses:
        "200":
          description: Generated questions
          content:
            application/json:
              schema:
                type: object
                properties:
                  questions:
                    type: array
                    items:
                      type: object
                      properties:
                        question:
                          type: string
                        follow_ups:
                          type: array
                          items:
                            type: string
                        intent:
                          type: string
                          enum: [comprehension, application, critical_thinking, synthesis, data_analysis]
        "422":
          description: Missing text or generation failed

/knowledge-base/ingest:
    post:
      summary: Ingest text content
      description: Ingests plain text into the workspace knowledge base. The content is chunked, embedded, and indexed asynchronously. Returns immediately with status "processing".
      tags: [Knowledge Base]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [content]
              properties:
                content:
                  type: string
                  description: The text content to ingest
                title:
                  type: string
                  description: Optional title for the knowledge base item
      responses:
        "201":
          description: Ingestion started
          content:
            application/json:
              schema:
                type: object
                properties:
                  knowledge_base_item:
                    $ref: "#/components/schemas/KnowledgeBaseItem"
        "401":
          description: Unauthorized or workspace access denied
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description: content parameter missing or ingestion failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

/knowledge-base:
    get:
      summary: List knowledge base items
      description: Returns a paginated list of knowledge base items in the workspace.
      tags: [Knowledge Base]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: source_type
          in: query
          schema:
            type: string
            enum: [text, website, pdf, document, youtube, voice]
          description: Filter by source type
        - name: status
          in: query
          schema:
            type: string
            enum: [draft, processing, ready, failed]
          description: Filter by status
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        "200":
          description: List of knowledge base items
          content:
            application/json:
              schema:
                type: object
                properties:
                  knowledge_base_items:
                    type: array
                    items:
                      $ref: "#/components/schemas/KnowledgeBaseItem"
                  total_count:
                    type: integer
                  page:
                    type: integer
                  per_page:
                    type: integer

/knowledge-base/{id}:
    get:
      summary: Get a knowledge base item
      description: Returns a single knowledge base item by ID.
      tags: [Knowledge Base]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Knowledge base item
          content:
            application/json:
              schema:
                type: object
                properties:
                  knowledge_base_item:
                    $ref: "#/components/schemas/KnowledgeBaseItem"
        "404":
          description: Item not found or belongs to a different workspace
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      summary: Delete a knowledge base item
      description: Permanently deletes a knowledge base item and its associated chunks.
      tags: [Knowledge Base]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Item deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
        "404":
          description: Item not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

/knowledge-base/search:
    post:
      summary: Search the knowledge base
      description: |
        Performs semantic vector search across the workspace knowledge base. Returns both raw text chunks and extracted insights ranked by relevance score.

Results include:
        - **chunks** — raw text segments from ingested documents
        - **insights** — structured data points (statistics, quotes, milestones, etc.) extracted from chunks by AI
      tags: [Knowledge Base]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [query]
              properties:
                query:
                  type: string
                  description: The search query
                source_type:
                  type: string
                  enum: [text, website, pdf, document, youtube, voice]
                  description: Filter results to a specific source type
                include_insights:
                  type: boolean
                  default: true
                  description: Set to false to return raw chunks only
                similarity_threshold:
                  type: number
                  description: Similarity threshold between 0 and 1 for filtering results
                limit:
                  type: integer
                  default: 10
                  minimum: 1
                  maximum: 50
      responses:
        "200":
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  query:
                    type: string
                  total_results:
                    type: integer
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/KnowledgeBaseSearchResultItem"
        "401":
          description: Unauthorized or workspace access denied
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description: query parameter missing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

/post-score:
    post:
      summary: Score a LinkedIn post
      description: |
        Analyzes a LinkedIn post text and returns a detailed score out of 10 across multiple criteria:
        Hook Quality, Clarity, Readability, Completeness, Call-To-Action, Originality, Grammar,
        and Content DNA Alignment (if Content DNA is configured for the workspace).
      tags: [Post Score]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text:
                  type: string
                  description: The LinkedIn post text to score
      responses:
        "200":
          description: Post score with per-criteria breakdown
          content:
            application/json:
              schema:
                type: object
                properties:
                  score:
                    type: array
                    items:
                      type: object
                      properties:
                        criteria_name:
                          type: string
                        criteria_title:
                          type: string
                        score:
                          type: integer
                        weight:
                          type: integer
                        suggestions_to_improve:
                          type: string
                        what_was_done_well:
                          type: string
        "422":
          description: Invalid input or scoring failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

/posts/{id}/comments:
    post:
      summary: Create auto-plug comments
      description: |
        Add auto-plug comments to a post. These comments are automatically published after the post goes live,
        with a configurable delay. Cannot add comments to already-published posts.
      tags: [Posts]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [comments]
              properties:
                comments:
                  type: array
                  items:
                    type: object
                    required: [text, post_after_time_unit, post_after_time_unit_count]
                    properties:
                      text:
                        type: string
                        description: The comment text
                      post_after_time_unit:
                        type: string
                        enum: [minutes, hours, days]
                        description: Time unit for the delay after post publication
                      post_after_time_unit_count:
                        type: integer
                        description: Number of time units to wait before posting the comment
                        example: 5
      responses:
        "201":
          description: Comments created
          content:
            application/json:
              schema:
                type: object
                properties:
                  comments:
                    type: array
                    items:
                      $ref: "#/components/schemas/AutoPlugComment"
                  errors:
                    type: array
                    items:
                      type: object
        "400":
          description: Cannot add comments to a published post
        "404":
          description: Post not found
    get:
      summary: List auto-plug comments
      description: Returns all auto-plug comments for a post.
      tags: [Posts]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: List of comments
          content:
            application/json:
              schema:
                type: object
                properties:
                  comments:
                    type: array
                    items:
                      $ref: "#/components/schemas/AutoPlugComment"
        "404":
          description: Post not found

/posts/{id}/comments/{comment_id}:
    delete:
      summary: Delete an auto-plug comment
      description: Deletes a specific auto-plug comment. Cannot delete comments on published posts.
      tags: [Posts]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: comment_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Comment deleted
        "404":
          description: Comment not found
        "422":
          description: Cannot delete comments on a published post

/company-pages:
    get:
      summary: List company pages
      description: |
        Returns all LinkedIn company pages connected to the workspace.
        Use the `id` from the response as `linked_in_company_page_id` when creating or queuing posts to publish from a company page.
      tags: [Company Pages]
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      responses:
        "200":
          description: List of company pages
          content:
            application/json:
              schema:
                type: object
                properties:
                  company_pages:
                    type: array
                    items:
                      $ref: "#/components/schemas/CompanyPage"

{"openapi":"3.0.3","info":{"title":"Supergrow External API","description":"The Supergrow External API allows you to programmatically manage workspaces, posts, content, and analytics for your LinkedIn content management workflow.\n\n## Authentication\nAll API requests require an API key passed in the `X-Api-Key` header.\n\n### Getting an API Key\nTo obtain an API key, please send an email to support@supergrow.ai with your request. Our team will respond with your unique API key and any additional information needed to get started.\n\n## Rate Limits\n- **3,600 requests per hour** per user\n- **5,000 requests per day** per user\n- **Content extraction:** 10 extractions per day per workspace\n\n## MCP Server\nSupergrow offers an MCP (Model Context Protocol) server that lets you manage your LinkedIn content directly from AI tools like Claude. Contact support@supergrow.ai to learn more.\n","version":"1.0.0","contact":{"url":"https://help.supergrow.ai"}},"servers":[{"url":"https://external-api.supergrow.ai/api/v1/external","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key"}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"}},"error_code":{"type":"string","nullable":true,"description":"Machine-readable error code (e.g. PAID_PLAN_REQUIRED)"}}},"Workspace":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"is_archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"role":{"type":"string","enum":["ADMIN","TEAM MEMBER","CLIENT","ORG_OWNER","ORG_ADMIN"]},"timezone":{"type":"string","nullable":true,"description":"Workspace timezone (e.g. \"Asia/Kolkata\"). Used for scheduling posts."},"language":{"type":"string","nullable":true,"description":"Workspace content language (e.g. \"English\", \"Hindi\")."}}},"AutoPlugComment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"post_id":{"type":"string","format":"uuid"},"text":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","published","failed"]},"post_after_time_unit":{"type":"string","enum":["minutes","hours","days"]},"post_after_time_unit_count":{"type":"integer"},"published_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"CompanyPage":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"url":{"type":"string"},"logo_url":{"type":"string"},"page_id":{"type":"string","description":"LinkedIn company page ID"}}},"Post":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"text":{"type":"string"},"image_urls":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","scheduled","published","failed","under_review","approved","needs_changes"]},"published_at":{"type":"string","format":"date-time","nullable":true},"published_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"video_title":{"type":"string","nullable":true},"carousel_title":{"type":"string","nullable":true},"file_url":{"type":"string","nullable":true},"publish_from_type":{"type":"string","enum":["personal","company"],"description":"Whether the post is published from a personal profile or company page"},"linked_in_company_page_id":{"type":"string","format":"uuid","nullable":true,"description":"The company page ID if publish_from_type is \"company\""},"likes_count":{"type":"integer","nullable":true},"comments_count":{"type":"integer","nullable":true},"reshares_count":{"type":"integer","nullable":true},"impressions_count":{"type":"integer","nullable":true},"app_url":{"type":"string","nullable":true,"description":"URL to edit the post in the Supergrow app"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ContentDna":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["analyzing","completed","failed"]},"linkedin_profile_url":{"type":"string"},"name":{"type":"string"},"current_role":{"type":"string"},"company":{"type":"string"},"industry":{"type":"string"},"experience_years":{"type":"integer"},"seniority_level":{"type":"string"},"expertise_areas":{"type":"array","items":{"type":"string"}},"main_topics":{"type":"array","items":{"type":"string"}},"target_customers":{"type":"array","items":{"type":"object"}},"content_positioning":{"type":"object"},"writing_style":{"type":"object"},"content_patterns":{"type":"object"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"LinkedInAccount":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"avatar_url":{"type":"string","nullable":true},"linked_in_profile_url":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"WeeklyReport":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"week_start_date":{"type":"string","format":"date"},"week_end_date":{"type":"string","format":"date"},"week_label":{"type":"string"},"status":{"type":"string"},"summary":{"type":"object","properties":{"posts_published":{"type":"integer"},"total_engagements":{"type":"integer"},"total_impressions":{"type":"integer"},"rolling_average_engagement":{"type":"number"},"vs_baseline_percentage":{"type":"number"},"vs_baseline_text":{"type":"string"}}},"best_performer":{"type":"object","nullable":true,"properties":{"post_id":{"type":"string"},"multiplier":{"type":"number"},"insight":{"type":"object"}}},"worst_performer":{"type":"object","nullable":true,"properties":{"post_id":{"type":"string"},"multiplier":{"type":"number"},"insight":{"type":"object"}}},"posts_breakdown":{"type":"array","items":{"type":"object"}},"audience_growth":{"type":"object","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"DailyAnalytic":{"type":"object","properties":{"date":{"type":"string","format":"date"},"impressions":{"type":"integer"},"engagements":{"type":"integer"},"reactions":{"type":"integer"},"comments":{"type":"integer"},"reshares":{"type":"integer"},"members_reached":{"type":"integer"}}},"ExtractionResult":{"type":"object","properties":{"text":{"type":"string"},"url":{"type":"string"}}},"KnowledgeBaseItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"source_type":{"type":"string","enum":["text","website","pdf","document","youtube","voice"]},"source_url":{"type":"string","nullable":true},"status":{"type":"string","enum":["draft","processing","ready","failed"]},"scope":{"type":"string","enum":["workspace","org"]},"chunks_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"KnowledgeBaseSearchResultItem":{"type":"object","properties":{"score":{"type":"number","format":"float","description":"Relevance score (0–1, higher is better)"},"entry_type":{"type":"string","enum":["chunk","insight","chunk_with_insight"]},"chunk":{"type":"object","nullable":true,"description":"The source text chunk (present for chunk and chunk_with_insight entries)","properties":{"id":{"type":"string"},"content":{"type":"string"},"content_preview":{"type":"string"},"chunk_index":{"type":"integer"},"token_count":{"type":"integer"}}},"insight":{"type":"object","nullable":true,"description":"Extracted insight (present for insight and chunk_with_insight entries)","properties":{"type":{"type":"string","enum":["statistic","quote","milestone","product_feature","customer_proof_point","contrarian_claim"]},"text":{"type":"string"},"confidence":{"type":"string","enum":["high","medium","low"]}}},"knowledge_base_item":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"source_type":{"type":"string"},"source_url":{"type":"string","nullable":true}}},"metadata":{"type":"object","description":"Additional metadata for the search result item."}}},"Pagination":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"per_page":{"type":"integer"},"pages":{"type":"integer"}}}},"parameters":{"WorkspaceId":{"name":"workspace_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"},"description":"The ID of the workspace"}}},"paths":{"/workspaces":{"get":{"summary":"List all workspaces","description":"Returns all workspaces accessible to the authenticated user, including their role in each.","tags":["Workspaces"],"responses":{"200":{"description":"List of workspaces","content":{"application/json":{"schema":{"type":"object","properties":{"workspaces":{"type":"array","items":{"$ref":"#/components/schemas/Workspace"}}}}}}}}}},"/posts":{"get":{"summary":"List posts","description":"Lists posts in a workspace filtered by status.","tags":["Posts"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"name":"status","in":"query","required":true,"schema":{"type":"string","enum":["draft","scheduled","published","failed","all"]}},{"name":"tag_ids","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated tag IDs"}],"responses":{"200":{"description":"List of posts","content":{"application/json":{"schema":{"type":"object","properties":{"posts":{"type":"array","items":{"$ref":"#/components/schemas/Post"}}}}}}}}},"post":{"summary":"Create a post","description":"Creates a new draft post in a workspace. Optionally publish from a company page by providing `linked_in_company_page_id`.\nUse `GET /company-pages` to list available company pages.\n","tags":["Posts"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":3000},"image_urls":{"type":"array","items":{"type":"string"}},"file_url":{"type":"string"},"carousel_title":{"type":"string"},"video_url":{"type":"string"},"video_title":{"type":"string"},"video_thumbnail_url":{"type":"string"},"linked_in_company_page_id":{"type":"string","format":"uuid","description":"Optional. If provided, the post will be published from this company page instead of the personal profile. Use GET /company-pages to list available pages."}}}}}},"responses":{"201":{"description":"Post created","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"post":{"$ref":"#/components/schemas/Post"}}}}}}}}},"/posts/{id}":{"get":{"summary":"Get a post","description":"Get details for a specific post.","tags":["Posts"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Post details","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"$ref":"#/components/schemas/Post"}}}}}}}},"put":{"summary":"Update a post","description":"Updates an existing draft post.","tags":["Posts"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":3000},"image_urls":{"type":"array","items":{"type":"string"}},"file_url":{"type":"string"},"carousel_title":{"type":"string"},"video_url":{"type":"string"},"video_title":{"type":"string"},"video_thumbnail_url":{"type":"string"}}}}}},"responses":{"200":{"description":"Post updated"}}},"delete":{"summary":"Delete a post","description":"Deletes a draft or failed post.","tags":["Posts"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Post deleted"}}}},"/posts/{id}/schedule":{"post":{"summary":"Schedule a post","description":"Schedules a post for publication at a specific time. Pass `hour` in the workspace's local timezone (NOT UTC). For example, for 2 PM IST pass hour=14.","tags":["Posts"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"day_of_week":{"type":"integer","description":"Day of week (0=Sunday, 1=Monday, ..., 6=Saturday)"},"hour":{"type":"integer","minimum":0,"maximum":23,"description":"Hour in the workspace's local timezone (0-23). Do NOT convert to UTC."},"minute":{"type":"integer","minimum":0,"maximum":59},"day_of_the_month":{"type":"integer","minimum":1,"maximum":31},"month":{"type":"integer","minimum":1,"maximum":12},"year":{"type":"integer"}}}}}},"responses":{"200":{"description":"Post scheduled"}}}},"/posts/{id}/unschedule":{"post":{"summary":"Unschedule a post","description":"Removes scheduling and reverts post to draft.","tags":["Posts"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Post unscheduled"}}}},"/posts/{id}/publish":{"post":{"summary":"Publish a post","description":"Immediately initiates the publishing process (asynchronous).","tags":["Posts"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Publishing initiated"}}}},"/posts/queue":{"post":{"summary":"Queue a post","description":"Creates a post and auto-schedules it in the next available time slot.\nOptionally publish from a company page by providing `linked_in_company_page_id`.\n","tags":["Posts"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":3000},"image_urls":{"type":"array","items":{"type":"string"}},"file_url":{"type":"string"},"carousel_title":{"type":"string"},"video_url":{"type":"string"},"video_title":{"type":"string"},"linked_in_company_page_id":{"type":"string","format":"uuid","description":"Optional. Publish from a company page instead of personal profile."}}}}}},"responses":{"201":{"description":"Post created and scheduled"}}}},"/posts/{id}/public-link":{"post":{"summary":"Create public preview link","description":"Creates a public link to preview a post. Returns the existing link if one already exists.","tags":["Posts"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Public link created","content":{"application/json":{"schema":{"type":"object","properties":{"public_url":{"type":"string","format":"uri"}}}}}},"404":{"description":"Post not found"}}},"delete":{"summary":"Remove public preview link","description":"Removes the public preview link from a post.","tags":["Posts"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Public link removed"}}}},"/content-dna":{"get":{"summary":"Get Content DNA","description":"Returns the Content DNA profile for the workspace — professional profile, writing style, content patterns, and target audience.","tags":["Content DNA"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}],"responses":{"200":{"description":"Content DNA profile","content":{"application/json":{"schema":{"type":"object","properties":{"content_dna":{"$ref":"#/components/schemas/ContentDna"}}}}}}}}},"/content-dna/regenerate":{"post":{"summary":"Regenerate Content DNA","description":"Triggers Content DNA regeneration for the workspace. Uses the LinkedIn profile URL\nfrom the connected LinkedIn account. No request body needed.\n","tags":["Content DNA"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}],"responses":{"200":{"description":"Regeneration started","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"content_dna":{"$ref":"#/components/schemas/ContentDna"}}}}}},"422":{"description":"No LinkedIn account connected or no profile URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/linked-in-accounts":{"get":{"summary":"Get LinkedIn accounts","description":"Returns LinkedIn accounts connected to the workspace. Sensitive tokens are never exposed.","tags":["LinkedIn Accounts"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}],"responses":{"200":{"description":"List of LinkedIn accounts","content":{"application/json":{"schema":{"type":"object","properties":{"linked_in_accounts":{"type":"array","items":{"$ref":"#/components/schemas/LinkedInAccount"}}}}}}}}}},"/calendar/weekly":{"get":{"summary":"Get weekly calendar","description":"Returns the weekly calendar view with time slots and scheduled posts.","tags":["Calendar"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"name":"offset","in":"query","schema":{"type":"integer","default":0},"description":"Week offset (0=current, 1=next, -1=last)"}],"responses":{"200":{"description":"Weekly calendar","content":{"application/json":{"schema":{"type":"object","properties":{"calendar":{"type":"object","description":"Weekly calendar data with time slots and associated posts"},"timezone":{"type":"string","example":"America/New_York","description":"The workspace's configured timezone"}}}}}}}}},"/calendar/monthly":{"get":{"summary":"Get monthly calendar","description":"Returns the monthly calendar view with time slots and scheduled posts.","tags":["Calendar"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"name":"offset","in":"query","schema":{"type":"integer","default":0},"description":"Month offset (0=current, 1=next, -1=last)"}],"responses":{"200":{"description":"Monthly calendar","content":{"application/json":{"schema":{"type":"object","properties":{"calendar":{"type":"object","description":"Monthly calendar data with time slots and associated posts"},"timezone":{"type":"string","example":"America/New_York","description":"The workspace's configured timezone"}}}}}}}}},"/kanban":{"get":{"summary":"Get kanban board","description":"Returns the kanban board with posts grouped by status.","tags":["Kanban"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","default":10,"maximum":100}}],"responses":{"200":{"description":"Kanban board"}}}},"/kanban/column":{"get":{"summary":"Get kanban column","description":"Returns posts for a single status column.","tags":["Kanban"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"name":"status","in":"query","required":true,"schema":{"type":"string","enum":["draft","under_review","approved","needs_changes","scheduled","published"]}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","default":10,"maximum":100}}],"responses":{"200":{"description":"Kanban column"}}}},"/analytics/weekly-reports":{"get":{"summary":"Get weekly reports","description":"Returns weekly content performance reports for the workspace.","tags":["Analytics"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"name":"limit","in":"query","schema":{"type":"integer","default":12}}],"responses":{"200":{"description":"List of weekly reports","content":{"application/json":{"schema":{"type":"object","properties":{"weekly_reports":{"type":"array","items":{"$ref":"#/components/schemas/WeeklyReport"}}}}}}}}}},"/analytics/followers":{"get":{"summary":"Get live followers data","description":"Returns live follower count and trend data from LinkedIn API.\nRate limited to 500 live analytics calls per day per workspace.\n","tags":["Analytics"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"name":"period","in":"query","schema":{"type":"string","enum":["last_7_days","last_30_days","current_month","previous_month"],"default":"last_7_days"},"description":"Predefined period (ignored if start_date/end_date provided)"},{"name":"start_date","in":"query","schema":{"type":"string","format":"date"},"description":"Custom start date (YYYY-MM-DD). Use with end_date."},{"name":"end_date","in":"query","schema":{"type":"string","format":"date"},"description":"Custom end date (YYYY-MM-DD). Use with start_date."}],"responses":{"200":{"description":"Followers data","content":{"application/json":{"schema":{"type":"object","properties":{"current_count":{"type":"integer"},"trend":{"type":"object"}}}}}},"422":{"description":"No LinkedIn account connected"}}}},"/analytics/metrics":{"get":{"summary":"Get live engagement metrics","description":"Returns live engagement metric trends from LinkedIn API.\nSupported metrics: IMPRESSION, MEMBERS_REACHED, RESHARE, REACTION, COMMENT.\nRate limited to 500 live analytics calls per day per workspace.\n","tags":["Analytics"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"name":"metric","in":"query","schema":{"type":"string","enum":["IMPRESSION","MEMBERS_REACHED","RESHARE","REACTION","COMMENT"],"default":"IMPRESSION"}},{"name":"period","in":"query","schema":{"type":"string","enum":["last_7_days","last_30_days","current_month","previous_month"],"default":"last_7_days"},"description":"Predefined period (ignored if start_date/end_date provided)"},{"name":"start_date","in":"query","schema":{"type":"string","format":"date"},"description":"Custom start date (YYYY-MM-DD). Use with end_date."},{"name":"end_date","in":"query","schema":{"type":"string","format":"date"},"description":"Custom end date (YYYY-MM-DD). Use with start_date."}],"responses":{"200":{"description":"Metric trend data","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"metric_type":{"type":"string"}}}}}},"422":{"description":"No LinkedIn account connected or invalid metric"}}}},"/extract":{"post":{"summary":"Extract text (auto-detect)","description":"Automatically detects URL type (webpage, YouTube, PDF, audio) and extracts text. Limited to 10 extractions per day per workspace.","tags":["Content Extraction"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"Extracted text","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractionResult"}}}},"429":{"description":"Daily extraction limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/extract/youtube":{"post":{"summary":"Extract YouTube transcript","description":"Extracts the transcript from a YouTube video. Limited to 10 extractions per day per workspace.","tags":["Content Extraction"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"YouTube transcript","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractionResult"}}}}}}},"/extract/pdf":{"post":{"summary":"Extract PDF text","description":"Extracts text content from a PDF file. Limited to 10 extractions per day per workspace.","tags":["Content Extraction"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"PDF text","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractionResult"}}}}}}},"/extract/audio":{"post":{"summary":"Transcribe audio","description":"Transcribes audio or video files to text. Limited to 10 extractions per day per workspace.\nSupported formats: mp3, mp4, wav, m4a, aac, ogg, flac, wma, avi, mov, wmv, flv, webm, mkv.\n","tags":["Content Extraction"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"Transcribed text","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractionResult"}}}}}}},"/questions/from-topic":{"post":{"summary":"Generate questions from a topic","description":"Generates 8-12 interview-style questions for a given topic. Questions are personalized\nusing the workspace's Content DNA (if available) and designed to extract insights\nfor LinkedIn content creation. Each question includes follow-up prompts.\n","tags":["Questions"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["topic"],"properties":{"topic":{"type":"string","description":"The topic to generate questions about"}}}}}},"responses":{"200":{"description":"Generated questions","content":{"application/json":{"schema":{"type":"object","properties":{"questions":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"follow_ups":{"type":"array","items":{"type":"string"}}}}}}}}}},"422":{"description":"Missing topic or generation failed"}}}},"/questions/from-text":{"post":{"summary":"Generate questions from text content","description":"Analyzes text content (article, blog post, transcript, etc.) and generates\ninterview-style questions to help extract insights for LinkedIn posts.\nQuestions are self-contained with context from the text.\n","tags":["Questions"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","description":"The text content to analyze and generate questions from"}}}}}},"responses":{"200":{"description":"Generated questions","content":{"application/json":{"schema":{"type":"object","properties":{"questions":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"follow_ups":{"type":"array","items":{"type":"string"}},"intent":{"type":"string","enum":["comprehension","application","critical_thinking","synthesis","data_analysis"]}}}}}}}}},"422":{"description":"Missing text or generation failed"}}}},"/knowledge-base/ingest":{"post":{"summary":"Ingest text content","description":"Ingests plain text into the workspace knowledge base. The content is chunked, embedded, and indexed asynchronously. Returns immediately with status \"processing\".","tags":["Knowledge Base"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string","description":"The text content to ingest"},"title":{"type":"string","description":"Optional title for the knowledge base item"}}}}}},"responses":{"201":{"description":"Ingestion started","content":{"application/json":{"schema":{"type":"object","properties":{"knowledge_base_item":{"$ref":"#/components/schemas/KnowledgeBaseItem"}}}}}},"401":{"description":"Unauthorized or workspace access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"content parameter missing or ingestion failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/knowledge-base":{"get":{"summary":"List knowledge base items","description":"Returns a paginated list of knowledge base items in the workspace.","tags":["Knowledge Base"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"name":"source_type","in":"query","schema":{"type":"string","enum":["text","website","pdf","document","youtube","voice"]},"description":"Filter by source type"},{"name":"status","in":"query","schema":{"type":"string","enum":["draft","processing","ready","failed"]},"description":"Filter by status"},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"List of knowledge base items","content":{"application/json":{"schema":{"type":"object","properties":{"knowledge_base_items":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBaseItem"}},"total_count":{"type":"integer"},"page":{"type":"integer"},"per_page":{"type":"integer"}}}}}}}}},"/knowledge-base/{id}":{"get":{"summary":"Get a knowledge base item","description":"Returns a single knowledge base item by ID.","tags":["Knowledge Base"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Knowledge base item","content":{"application/json":{"schema":{"type":"object","properties":{"knowledge_base_item":{"$ref":"#/components/schemas/KnowledgeBaseItem"}}}}}},"404":{"description":"Item not found or belongs to a different workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a knowledge base item","description":"Permanently deletes a knowledge base item and its associated chunks.","tags":["Knowledge Base"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Item deleted","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"}}}}}},"404":{"description":"Item not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/knowledge-base/search":{"post":{"summary":"Search the knowledge base","description":"Performs semantic vector search across the workspace knowledge base. Returns both raw text chunks and extracted insights ranked by relevance score.\n\nResults include:\n- **chunks** — raw text segments from ingested documents\n- **insights** — structured data points (statistics, quotes, milestones, etc.) extracted from chunks by AI\n","tags":["Knowledge Base"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"The search query"},"source_type":{"type":"string","enum":["text","website","pdf","document","youtube","voice"],"description":"Filter results to a specific source type"},"include_insights":{"type":"boolean","default":true,"description":"Set to false to return raw chunks only"},"similarity_threshold":{"type":"number","description":"Similarity threshold between 0 and 1 for filtering results"},"limit":{"type":"integer","default":10,"minimum":1,"maximum":50}}}}}},"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"total_results":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBaseSearchResultItem"}}}}}}},"401":{"description":"Unauthorized or workspace access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"query parameter missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/post-score":{"post":{"summary":"Score a LinkedIn post","description":"Analyzes a LinkedIn post text and returns a detailed score out of 10 across multiple criteria:\nHook Quality, Clarity, Readability, Completeness, Call-To-Action, Originality, Grammar,\nand Content DNA Alignment (if Content DNA is configured for the workspace).\n","tags":["Post Score"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","description":"The LinkedIn post text to score"}}}}}},"responses":{"200":{"description":"Post score with per-criteria breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"score":{"type":"array","items":{"type":"object","properties":{"criteria_name":{"type":"string"},"criteria_title":{"type":"string"},"score":{"type":"integer"},"weight":{"type":"integer"},"suggestions_to_improve":{"type":"string"},"what_was_done_well":{"type":"string"}}}}}}}}},"422":{"description":"Invalid input or scoring failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/posts/{id}/comments":{"post":{"summary":"Create auto-plug comments","description":"Add auto-plug comments to a post. These comments are automatically published after the post goes live,\nwith a configurable delay. Cannot add comments to already-published posts.\n","tags":["Posts"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["comments"],"properties":{"comments":{"type":"array","items":{"type":"object","required":["text","post_after_time_unit","post_after_time_unit_count"],"properties":{"text":{"type":"string","description":"The comment text"},"post_after_time_unit":{"type":"string","enum":["minutes","hours","days"],"description":"Time unit for the delay after post publication"},"post_after_time_unit_count":{"type":"integer","description":"Number of time units to wait before posting the comment","example":5}}}}}}}}},"responses":{"201":{"description":"Comments created","content":{"application/json":{"schema":{"type":"object","properties":{"comments":{"type":"array","items":{"$ref":"#/components/schemas/AutoPlugComment"}},"errors":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Cannot add comments to a published post"},"404":{"description":"Post not found"}}},"get":{"summary":"List auto-plug comments","description":"Returns all auto-plug comments for a post.","tags":["Posts"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"List of comments","content":{"application/json":{"schema":{"type":"object","properties":{"comments":{"type":"array","items":{"$ref":"#/components/schemas/AutoPlugComment"}}}}}}},"404":{"description":"Post not found"}}}},"/posts/{id}/comments/{comment_id}":{"delete":{"summary":"Delete an auto-plug comment","description":"Deletes a specific auto-plug comment. Cannot delete comments on published posts.","tags":["Posts"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"comment_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Comment deleted"},"404":{"description":"Comment not found"},"422":{"description":"Cannot delete comments on a published post"}}}},"/company-pages":{"get":{"summary":"List company pages","description":"Returns all LinkedIn company pages connected to the workspace.\nUse the `id` from the response as `linked_in_company_page_id` when creating or queuing posts to publish from a company page.\n","tags":["Company Pages"],"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}],"responses":{"200":{"description":"List of company pages","content":{"application/json":{"schema":{"type":"object","properties":{"company_pages":{"type":"array","items":{"$ref":"#/components/schemas/CompanyPage"}}}}}}}}}}}}