Aidelly AI Analytics API

openapi: 3.2.0
info:
  title: Aidelly Public Analytics API
  version: 1.1.0
  x-versioning-policy: https://www.aidelly.ai/developers/api/deprecation
  description: 'Customer-facing API for publishing and scheduling social posts through Aidelly.

    All responses use `{ success, data | error, request_id }`.


    This API is optimized for single-user project integrations and AI agents:

    - deterministic error codes

    - required idempotency on writes

    - plan-aware rate-limit headers on authenticated responses'
servers:
- url: https://app.aidelly.ai/api/public/v1
security:
- bearerAuth: []
tags:
- name: Analytics
paths:
  /analytics/summary:
    get:
      tags:
      - Analytics
      summary: Get analytics summary
      operationId: getAnalyticsSummary
      description: 'Get aggregated analytics summary for a workspace. Workspace context is required

        (pass workspace_id via x-aidelly-workspace-id header or MCP workspace_id).

        Metrics are aggregated across all connected accounts in the workspace.'
      parameters:
      - in: query
        name: timeframe
        schema:
          type: string
          pattern: ^\d+d$
          default: 7d
        description: 'Time window in days (e.g. 7d, 30d). Min: 1d, Max: 365d. Default: 7d'
      - in: query
        name: startDate
        schema:
          type: string
          format: date
        description: ISO date string (YYYY-MM-DD). Overrides timeframe if provided.
      - in: query
        name: endDate
        schema:
          type: string
          format: date
        description: ISO date string (YYYY-MM-DD). End of range (inclusive).
      - in: query
        name: includeInsights
        schema:
          type: boolean
          default: true
        description: Include AI-generated insights (if available).
      - in: query
        name: includeActivity
        schema:
          type: boolean
          default: false
        description: Include recent activity logs (reserved for future use).
      responses:
        '200':
          $ref: '#/components/responses/UsageEnvelopeResponse'
        '400':
          description: Invalid query or missing workspace context (PUBLIC_API_WORKSPACE_REQUIRED or PUBLIC_API_QUERY_INVALID)
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalErrorResponse'
      x-tool-name: aidelly_get_analytics_summary
      x-scope: analytics:read
      x-tool-description: Summarize workspace analytics for a timeframe (for example 30d) or a startDate/endDate range, for workspace_id. summary.platformMetrics holds the per-channel metrics used to compare channels. One call covers one range; a trend comes from comparing two separate ranges. Read-only.
      security:
      - bearerAuth: []
      - oauth2:
        - analytics:read
  /analytics/unified:
    get:
      tags:
      - Analytics
      summary: Get unified analytics rows
      operationId: getAnalyticsUnified
      description: 'Fetch unified analytics rows (mart + live provider data) for a workspace.

        X data is never read live here; it comes from the last in-app refresh or nightly run.

        Workspace context is required (pass workspace_id via x-aidelly-workspace-id header or MCP workspace_id).

        Each row represents metrics for a post/account on a specific date.

        Date parameters must be ISO dates (YYYY-MM-DD); full ISO timestamps are rejected.'
      parameters:
      - in: query
        name: from
        required: true
        schema:
          type: string
          format: date
        description: Start date (YYYY-MM-DD, required). ISO timestamps will be rejected.
      - in: query
        name: to
        required: true
        schema:
          type: string
          format: date
        description: End date (YYYY-MM-DD, required, inclusive). ISO timestamps will be rejected.
      - in: query
        name: platforms
        schema:
          type: string
        description: Comma-separated list of platforms to include (e.g. x,instagram,tiktok). If omitted, all platforms are returned.
      responses:
        '200':
          $ref: '#/components/responses/UsageEnvelopeResponse'
        '400':
          description: Invalid query or missing workspace context (PUBLIC_API_WORKSPACE_REQUIRED or PUBLIC_API_QUERY_INVALID)
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalErrorResponse'
      x-tool-name: aidelly_get_analytics_unified
      x-scope: analytics:read
      x-tool-description: Read unified social analytics rows for workspace_id, combining stored and live provider metrics. Requires from and to as YYYY-MM-DD dates, not timestamps; optionally filter platforms with a comma-separated list. Returns metrics by post, account, and date.
      security:
      - bearerAuth: []
      - oauth2:
        - analytics:read
  /analytics/insights:
    get:
      tags:
      - Analytics
      summary: List analytics insights
      operationId: listAnalyticsInsights
      description: 'List AI-generated analytics insights for a workspace. Workspace context is required

        (pass workspace_id via x-aidelly-workspace-id header or MCP workspace_id).

        Insights are only available after generation (via POST /analytics/insights or in-app).'
      parameters:
      - in: query
        name: platforms
        schema:
          type: string
        description: Comma-separated list of platforms to filter by (e.g. x,instagram).
      - in: query
        name: limit
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        description: 'Maximum number of insights to return. Default: 10'
      - in: query
        name: type
        schema:
          type: string
        description: Filter by insight type (e.g. performance, content, engagement).
      - in: query
        name: dismissed
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
        description: Filter by dismissed status. If omitted, returns both.
      - in: query
        name: cursor
        description: Opaque cursor from a previous response's `next_cursor`. Treat it as opaque; its encoding is not part of the contract. Omit to start at the first page. When both `cursor` and offset-style parameters are sent, the cursor wins.
        schema:
          type: string
          maxLength: 512
      responses:
        '200':
          $ref: '#/components/responses/UsageEnvelopeResponse'
        '400':
          description: Invalid query or missing workspace context (PUBLIC_API_WORKSPACE_REQUIRED or PUBLIC_API_QUERY_INVALID)
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalErrorResponse'
      x-tool-name: aidelly_get_analytics_insights
      x-scope: analytics:read
      x-tool-description: Read saved analytics insights for the workspace. May return an empty list. Reading generates nothing (aidelly_generate_analytics_insights does), and saved insights are not limited to the analytics summary date range, so a missing or stale insight is not evidence of a trend. Read-only.
      security:
      - bearerAuth: []
      - oauth2:
        - analytics:read
    post:
      tags:
      - Analytics
      summary: Regenerate analytics insights
      operationId: regenerateAnalyticsInsights
      description: 'Trigger AI-powered analytics insights generation for a workspace.

        Workspace context is required (pass workspace_id via x-aidelly-workspace-id header or MCP workspace_id).'
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                platforms:
                  type: array
                  items:
                    type: string
                  description: Platforms to analyze for insights.
                regenerate:
                  type: boolean
                  description: If true, force regeneration even if insights exist.
                coach:
                  type: boolean
                  default: false
                  description: 'Opt in to the AI period coach: patterns across the period''s posts (what to repeat, change, and test next).

                    Costs 12 AI credits per run, charged to the API key''s user. Default false keeps the free rule-based insights.

                    Needs enough published posts; with too little data, or while the coach is not enabled, the response is the

                    rule-based insights plus `coachUnavailable` and nothing is charged.

                    '
                date_from:
                  type: string
                  format: date
                  description: Coach only. First day (YYYY-MM-DD). Defaults to 30 days before date_to; the range is at most 90 days.
                date_to:
                  type: string
                  format: date
                  description: Coach only. Last day (YYYY-MM-DD, not in the future). Defaults to today (UTC).
                platform:
                  type: string
                  description: Coach only. Limit the coach to one platform (e.g. instagram, x). When omitted and `platforms` has exactly one entry, that entry is used; otherwise the coach runs across all platforms.
      responses:
        '200':
          description: 'Insights envelope. With `coach: true` and enough data the response keeps `insights[]` (one entry per coach pattern,

            `metadata.coachRunId` and `metadata.evidencePostIds`) and adds `coach` with `runId`, `summary`, `patterns`, `repeat`,

            `change` and `testNext`; the run is saved with trigger `api`. `coach.runId` is null when the run could not be saved; the call was still charged and the result is complete. When the coach could not run, `coachUnavailable`

            is `disabled`, `insufficient_data` or `generation_failed`, `insights[]` is the rule-based output, and nothing is charged.

            '
          $ref: '#/components/responses/UsageEnvelopeResponse'
        '400':
          description: Invalid request or missing workspace context (PUBLIC_API_WORKSPACE_REQUIRED or PUBLIC_API_BODY_INVALID, including a coach range over 90 days)
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '429':
          description: Rate limited, or (coach only) out of AI credits (PUBLIC_API_PLAN_LIMIT_EXCEEDED, limit key ai_credits.text), or (coach only) more than 5 coach runs a minute for the API key (PUBLIC_API_RATE_LIMITED, with Retry-After)
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalErrorResponse'
        '503':
          description: Coach only. The AI credit charge could not be recorded, so the result was withheld (PUBLIC_API_AI_CREDIT_CHARGE_FAILED). Retry with the same idempotency key.
      x-tool-name: aidelly_generate_analytics_insights
      x-tool-aliases:
      - aidelly_post_analytics_insights
      x-scope: analytics:write
      x-tool-description: 'Generate and save AI analytics insights for workspace_id, optionally limited to platforms. regenerate=true forces a fresh analysis even when insights already exist. Default is free rule-based insights; opt in with coach: true for AI patterns across the period (optional date_from, date_to up to 90 days, platform); coach costs 12 credits, and with too little data it falls back to rule-based with a coachUnavailable reason and no charge. aidelly_get_analytics_insights reads saved insights without generating new ones. Retry-safe: a repeat call with the same idempotency_key returns the original result and is not charged again. Coach runs are limited to 5 a minute per API key.'
      security:
      - bearerAuth: []
      - oauth2:
        - analytics:write
    patch:
      tags:
      - Analytics
      summary: Apply analytics insight action
      operationId: updateAnalyticsInsight
      description: 'Perform an action on an analytics insight (view, dismiss, act_upon).

        Workspace context is required (pass workspace_id via x-aidelly-workspace-id header or MCP workspace_id).'
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                insightId:
                  type: string
                  description: ID of the insight to act upon.
                action:
                  type: string
                  enum:
                  - view
                  - dismiss
                  - act_upon
                  description: Action to perform.
      responses:
        '200':
          $ref: '#/components/responses/UsageEnvelopeResponse'
        '400':
          description: Invalid request or missing workspace context (PUBLIC_API_WORKSPACE_REQUIRED or PUBLIC_API_BODY_INVALID)
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalErrorResponse'
      x-tool-name: aidelly_update_analytics_insight
      x-tool-aliases:
      - aidelly_patch_analytics_insights
      x-scope: analytics:write
      x-tool-description: 'Update the recorded state of an analytics insight in workspace_id. Supply insightId and action (view, dismiss, or act_upon). Marks the insight as viewed, dismissed, or acted upon; it does not carry out the recommendation itself. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
      security:
      - bearerAuth: []
      - oauth2:
        - analytics:write
components:
  headers:
    XRateLimitLimit:
      description: Maximum requests allowed in the current window.
      schema:
        type: integer
        example: 120
    XRateLimitPlan:
      description: Resolved plan tier for rate limiting.
      schema:
        type: string
        enum:
        - launch
        - scale
        - agency
        - fallback
        example: scale
    XRateLimitResetEpoch:
      description: Unix epoch seconds for current window reset.
      schema:
        type: integer
        example: 1771353600
    RateLimitLimit:
      description: RFC 9333 maximum requests allowed in the current window.
      schema:
        type: integer
        minimum: 0
        example: 120
    XRateLimitWindowSeconds:
      description: Rate limit window duration in seconds.
      schema:
        type: integer
        example: 60
    RateLimitPolicy:
      description: Quota policy extension using limit and window parameters.
      schema:
        type: string
        example: 120;w=60
    RateLimitRemaining:
      description: RFC 9333 requests remaining in the current window.
      schema:
        type: integer
        minimum: 0
        example: 118
    XRateLimitReset:
      description: ISO timestamp for current window reset.
      schema:
        type: string
        format: date-time
        example: 2026-02-17 18:40:00+00:00
    XRateLimitRemaining:
      description: Remaining requests available in the current window.
      schema:
        type: integer
        example: 118
    RateLimitReset:
      description: RFC 9333 seconds until the current window resets.
      schema:
        type: integer
        minimum: 1
        example: 42
    RetryAfter:
      description: Seconds to wait before retrying after a `429`.
      schema:
        type: integer
        minimum: 1
        example: 17
  schemas:
    EnvelopeBase:
      type: object
      required:
      - success
      - request_id
      properties:
        success:
          type: boolean
        request_id:
          type: string
          format: uuid
    UsageEnvelope:
      allOf:
      - $ref: '#/components/schemas/EnvelopeBase'
      - type: object
        properties:
          success:
            const: true
          data:
            type: object
            additionalProperties: true
    PlanLimitErrorDetails:
      type: object
      additionalProperties: false
      required:
      - limit_key
      - plan_tier
      - current_usage
      - limit
      - reset_at
      - recommended_plan
      - upgrade_url
      properties:
        limit_key:
          type: string
          example: automations.active
        plan_tier:
          type: string
          example: launch
        current_usage:
          type: integer
          nullable: true
          example: 5
        limit:
          type: integer
          nullable: true
          example: 5
        reset_at:
          type: string
          format: date-time
          nullable: true
          example: 2026-03-31 23:59:59+00:00
        recommended_plan:
          type: string
          nullable: true
          example: scale
        upgrade_url:
          type: string
          format: uri
          example: https://app.aidelly.ai/account/billing
    ErrorEnvelope:
      allOf:
      - $ref: '#/components/schemas/EnvelopeBase'
      - type: object
        required:
        - error
        properties:
          success:
            const: false
          error:
            type: object
            required:
            - code
            - message
            properties:
              code:
                type: string
              message:
                type: string
              details:
                description: Machine-readable error details object. Plan/feature gates use PlanLimitErrorDetails.
                oneOf:
                - $ref: '#/components/schemas/PlanLimitErrorDetails'
                - type: object
                  additionalProperties: true
  responses:
    NotFoundResponse:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: PUBLIC_API_POST_NOT_FOUND
              message: Post not found.
            request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
    UnauthorizedResponse:
      description: API key missing, invalid, or expired
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: PUBLIC_API_AUTH_REQUIRED
              message: A Bearer API key is required.
            request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
    ForbiddenResponse:
      description: API key scope or context restriction failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: PUBLIC_API_SCOPE_FORBIDDEN
              message: The API key does not include required scopes.
              details:
                missing_scopes:
                - posts:write
            request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
    InternalErrorResponse:
      description: Unexpected server-side failure
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: PUBLIC_API_POST_CREATE_FAILED
              message: Unable to create scheduled post.
            request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
    BadRequestResponse:
      description: Request validation failed (body, missing Idempotency-Key, or invalid Idempotency-Key)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            bodyInvalid:
              value:
                success: false
                error:
                  code: PUBLIC_API_BODY_INVALID
                  message: Invalid request body.
                request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
            idempotencyKeyInvalid:
              value:
                success: false
                error:
                  code: PUBLIC_API_IDEMPOTENCY_KEY_INVALID
                  message: 'Idempotency-Key must be 1-255 printable ASCII characters with no spaces (letters, digits, and punctuation such as - _ : . are allowed).'
                request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
    UsageEnvelopeResponse:
      description: Generic successful response envelope
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/XRateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/XRateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/XRateLimitReset'
        X-RateLimit-Reset-Epoch:
          $ref: '#/components/headers/XRateLimitResetEpoch'
        X-RateLimit-Window-Seconds:
          $ref: '#/components/headers/XRateLimitWindowSeconds'
        X-RateLimit-Plan:
          $ref: '#/components/headers/XRateLimitPlan'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UsageEnvelope'
    RateLimitedResponse:
      description: API key exceeded allowed request throughput
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        X-RateLimit-Limit:
          $ref: '#/components/headers/XRateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/XRateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/XRateLimitReset'
        X-RateLimit-Reset-Epoch:
          $ref: '#/components/headers/XRateLimitResetEpoch'
        X-RateLimit-Window-Seconds:
          $ref: '#/components/headers/XRateLimitWindowSeconds'
        X-RateLimit-Plan:
          $ref: '#/components/headers/XRateLimitPlan'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: PUBLIC_API_RATE_LIMITED
              message: Rate limit exceeded.
            request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
  parameters:
    IdempotencyKey:
      in: header
      name: Idempotency-Key
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 255
        pattern: ^[\x21-\x7E]{1,255}$
        example: order-123:create-post:v1
      description: 'Required on all write endpoints. 1-255 printable ASCII characters (0x21-0x7E): letters, digits, and punctuation such as `-`, `_`, `.`, and `:` are allowed; spaces, control characters, and non-ASCII are not. Leading and trailing whitespace is trimmed. An invalid key returns 400 `PUBLIC_API_IDEMPOTENCY_KEY_INVALID`; a missing key returns 400 `PUBLIC_API_IDEMPOTENCY_REQUIRED`. Keys are scoped to the API key, method, and path.'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.aidelly.ai/api/mcp/oauth/authorize
          tokenUrl: https://app.aidelly.ai/api/mcp/oauth/token
          refreshUrl: https://app.aidelly.ai/api/mcp/oauth/token
          scopes:
            posts:write: Create and modify posts
            posts:read: Read access to posts
            photos:write: Create and modify photos
            media:write: Create and modify media
            connections:read: Read access to connections
            webhooks:manage: Manage webhooks
            approvals:read: Read access to approvals
            approvals:write: Create and modify approvals
            inbox:read: Read access to inbox
            inbox:write: Create and modify inbox
            automations:read: Read access to automations
            automations:write: Create and modify automations
            queues:read: Read access to queues
            queues:write: Create and modify queues
            destination-presets:read: Read access to destination-presets
            destination-presets:write: Create and modify destination-presets
            calendar:read: Read access to calendar
            calendar:write: Create and modify calendar
            analytics:read: Read access to analytics
            analytics:write: Create and modify analytics
            brand:read: Read access to brand
            brand:write: Create and modify brand
            workspaces:read: Read access to workspaces
            workspaces:write: Create and modify workspaces
            team:read: Read access to team
            team:write: Create and modify team
            repurpose:read: Read access to repurpose
            repurpose:write: Create and modify repurpose
            ideas:read: Read access to ideas
            ideas:write: Create and modify ideas
            links:read: Read access to links
            links:write: Create and modify links
            connect_links:read: Read access to connect_links
            connect_links:write: Create and modify connect_links
            bio:read: Read access to bio
            bio:write: Create and modify bio
            image_editor:read: Read access to image_editor
            image_editor:write: Create and modify image_editor
            viral_trends:read: Read access to viral_trends
            creators:read: Read access to creators
            creators:write: Create and modify creators
            competitors:read: Read access to competitors
            competitors:write: Create and modify competitors
            reports:read: Read access to reports
            reports:write: Create and modify reports
            tasks:read: Read access to tasks
            tasks:write: Create and modify tasks
            white-label:read: Read access to white-label
            white-label:write: Create and modify white-label
            drafts:read: Read access to drafts
            drafts:write: Create and modify drafts
            activity:read: Read access to activity
            credits:read: Read access to credits
            comments:read: Read access to comments
            comments:write: Create and modify comments
            prompts:read: Read access to prompts
            prompts:write: Create and modify prompts
externalDocs:
  description: Aidelly developer documentation and API lifecycle policy
  url: https://www.aidelly.ai/docs