Memesio API Contracts — growth

naftiko: 1.0.0-alpha2
info:
  label: Memesio API Contracts — growth
  description: 'Memesio API Contracts — growth. 18 operations. Lead operation: Decision Service for Growth Experiments with
    Optional Exposure Logging. Self-contained Naftiko capability covering one Memesio business surface.'
  tags:
  - Memesio
  - growth
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    MEMESIO_API_KEY: MEMESIO_API_KEY
capability:
  consumes:
  - type: http
    namespace: memesio-growth
    baseUri: ''
    description: Memesio API Contracts — growth business capability. Self-contained, no shared references.
    resources:
    - name: api-growth-experiments-decision
      path: /api/growth/experiments/decision
      operations:
      - name: get
        method: GET
        description: Decision Service for Growth Experiments with Optional Exposure Logging
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: actorId
          in: query
          type: string
          required: true
        - name: surface
          in: query
          type: string
        - name: logExposure
          in: query
          type: boolean
      - name: post
        method: POST
        description: Request Decisions or Query Exposure History for Growth Experiments
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-growth-lifecycle-messaging
      path: /api/growth/lifecycle-messaging
      operations:
      - name: get
        method: GET
        description: Get Lifecycle Messaging Flow Config and Recent Dispatch History
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: post
        method: POST
        description: Preview/Run Lifecycle Messaging Flows (Activation, Resurrection, Upgrade)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-growth-referrals
      path: /api/growth/referrals
      operations:
      - name: get
        method: GET
        description: Get Referral Credits for Actor
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: actorId
          in: query
          type: string
      - name: post
        method: POST
        description: Create or Redeem Referral Invite Code with Fraud Checks
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-growth-social-publish
      path: /api/growth/social-publish
      operations:
      - name: get
        method: GET
        description: Get Social Publish Gate State, Connected Accounts, and Recent Publishes
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: actorId
          in: query
          type: string
          required: true
        - name: publishLimit
          in: query
          type: integer
      - name: post
        method: POST
        description: Connect/Disconnect Social Accounts and One-Click Publish (Phase-Gated)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-growth-trend-campaigns
      path: /api/growth/trend-campaigns
      operations:
      - name: get
        method: GET
        description: Generate or Retrieve Weekly Trend-Driven Template Campaigns
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: weekStart
          in: query
          type: string
        - name: limit
          in: query
          type: integer
        - name: publishedOnly
          in: query
          type: boolean
      - name: post
        method: POST
        description: Publish Weekly Trend-Driven Template Campaigns for Marketing Ops
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-growth-viral-triggers
      path: /api/growth/viral-triggers
      operations:
      - name: get
        method: GET
        description: Get Viral Loop Trigger Definitions and Instrumentation Mapping
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: api-v1-agents-rewards-leaderboard
      path: /api/v1/agents/rewards/leaderboard
      operations:
      - name: get
        method: GET
        description: Get Weekly Meme Leaderboard
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: weekStart
          in: query
          type: string
        - name: limit
          in: query
          type: integer
    - name: api-v1-agents-rewards-votes
      path: /api/v1/agents/rewards/votes
      operations:
      - name: post
        method: POST
        description: Cast Weekly Meme Vote (Deduped by Voter Hash)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-v1-agents-rewards-winner:close
      path: /api/v1/agents/rewards/winner:close
      operations:
      - name: post
        method: POST
        description: Close Weekly Winner Record for Manual Payout Workflow
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-v1-agents-unlocks-unlockId-approve
      path: /api/v1/agents/unlocks/{unlockId}/approve
      operations:
      - name: post
        method: POST
        description: Admin Approval for Social Unlock and Quota Boost
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: unlockId
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-v1-agents-agentId-unlocks-social-action
      path: /api/v1/agents/{agentId}/unlocks/social-action
      operations:
      - name: post
        method: POST
        description: Submit Social Action Proof (X_follow) for Quota Boost Review
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: agentId
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-video-export-settings
      path: /api/video/export-settings
      operations:
      - name: get
        method: GET
        description: Get Export Preset Catalog (TikTok, Reels, Shorts, MP4 Square) and Optional Watermark Decision Preview
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: planTier
          in: query
          type: string
        - name: presetId
          in: query
          type: string
        - name: container
          in: query
          type: string
        - name: bitrateKbps
          in: query
          type: number
        - name: watermarkEnabled
          in: query
          type: boolean
        - name: watermarkText
          in: query
          type: string
      - name: post
        method: POST
        description: Evaluate Export Settings with Plan-Tier Watermark Rules for TikTok/Reels/Shorts/MP4 Square Presets
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    authentication:
      type: apikey
      key: x-developer-api-key
      value: '{{env.MEMESIO_API_KEY}}'
      placement: header
  exposes:
  - type: rest
    namespace: memesio-growth-rest
    port: 8080
    description: REST adapter for Memesio API Contracts — growth. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/api/growth/experiments/decision
      name: api-growth-experiments-decision
      description: REST surface for api-growth-experiments-decision.
      operations:
      - method: GET
        name: get
        description: Decision Service for Growth Experiments with Optional Exposure Logging
        call: memesio-growth.get
        with:
          actorId: rest.actorId
          surface: rest.surface
          logExposure: rest.logExposure
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: post
        description: Request Decisions or Query Exposure History for Growth Experiments
        call: memesio-growth.post
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/growth/lifecycle-messaging
      name: api-growth-lifecycle-messaging
      description: REST surface for api-growth-lifecycle-messaging.
      operations:
      - method: GET
        name: get
        description: Get Lifecycle Messaging Flow Config and Recent Dispatch History
        call: memesio-growth.get
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: post
        description: Preview/Run Lifecycle Messaging Flows (Activation, Resurrection, Upgrade)
        call: memesio-growth.post
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/growth/referrals
      name: api-growth-referrals
      description: REST surface for api-growth-referrals.
      operations:
      - method: GET
        name: get
        description: Get Referral Credits for Actor
        call: memesio-growth.get
        with:
          actorId: rest.actorId
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: post
        description: Create or Redeem Referral Invite Code with Fraud Checks
        call: memesio-growth.post
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/growth/social-publish
      name: api-growth-social-publish
      description: REST surface for api-growth-social-publish.
      operations:
      - method: GET
        name: get
        description: Get Social Publish Gate State, Connected Accounts, and Recent Publishes
        call: memesio-growth.get
        with:
          actorId: rest.actorId
          publishLimit: rest.publishLimit
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: post
        description: Connect/Disconnect Social Accounts and One-Click Publish (Phase-Gated)
        call: memesio-growth.post
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/growth/trend-campaigns
      name: api-growth-trend-campaigns
      description: REST surface for api-growth-trend-campaigns.
      operations:
      - method: GET
        name: get
        description: Generate or Retrieve Weekly Trend-Driven Template Campaigns
        call: memesio-growth.get
        with:
          weekStart: rest.weekStart
          limit: rest.limit
          publishedOnly: rest.publishedOnly
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: post
        description: Publish Weekly Trend-Driven Template Campaigns for Marketing Ops
        call: memesio-growth.post
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/growth/viral-triggers
      name: api-growth-viral-triggers
      description: REST surface for api-growth-viral-triggers.
      operations:
      - method: GET
        name: get
        description: Get Viral Loop Trigger Definitions and Instrumentation Mapping
        call: memesio-growth.get
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/agents/rewards/leaderboard
      name: api-v1-agents-rewards-leaderboard
      description: REST surface for api-v1-agents-rewards-leaderboard.
      operations:
      - method: GET
        name: get
        description: Get Weekly Meme Leaderboard
        call: memesio-growth.get
        with:
          weekStart: rest.weekStart
          limit: rest.limit
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/agents/rewards/votes
      name: api-v1-agents-rewards-votes
      description: REST surface for api-v1-agents-rewards-votes.
      operations:
      - method: POST
        name: post
        description: Cast Weekly Meme Vote (Deduped by Voter Hash)
        call: memesio-growth.post
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/agents/rewards/winner-close
      name: api-v1-agents-rewards-winner-close
      description: REST surface for api-v1-agents-rewards-winner:close.
      operations:
      - method: POST
        name: post
        description: Close Weekly Winner Record for Manual Payout Workflow
        call: memesio-growth.post
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/agents/unlocks/{unlockid}/approve
      name: api-v1-agents-unlocks-unlockid-approve
      description: REST surface for api-v1-agents-unlocks-unlockId-approve.
      operations:
      - method: POST
        name: post
        description: Admin Approval for Social Unlock and Quota Boost
        call: memesio-growth.post
        with:
          unlockId: rest.unlockId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/agents/{agentid}/unlocks/social-action
      name: api-v1-agents-agentid-unlocks-social-action
      description: REST surface for api-v1-agents-agentId-unlocks-social-action.
      operations:
      - method: POST
        name: post
        description: Submit Social Action Proof (X_follow) for Quota Boost Review
        call: memesio-growth.post
        with:
          agentId: rest.agentId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/video/export-settings
      name: api-video-export-settings
      description: REST surface for api-video-export-settings.
      operations:
      - method: GET
        name: get
        description: Get Export Preset Catalog (TikTok, Reels, Shorts, MP4 Square) and Optional Watermark Decision Preview
        call: memesio-growth.get
        with:
          planTier: rest.planTier
          presetId: rest.presetId
          container: rest.container
          bitrateKbps: rest.bitrateKbps
          watermarkEnabled: rest.watermarkEnabled
          watermarkText: rest.watermarkText
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: post
        description: Evaluate Export Settings with Plan-Tier Watermark Rules for TikTok/Reels/Shorts/MP4 Square Presets
        call: memesio-growth.post
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: memesio-growth-mcp
    port: 9090
    transport: http
    description: MCP adapter for Memesio API Contracts — growth. One tool per consumed operation, routed inline through this
      capability's consumes block.
    tools:
    - name: decision-service-growth-experiments-optional
      description: Decision Service for Growth Experiments with Optional Exposure Logging
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: memesio-growth.get
      with:
        actorId: tools.actorId
        surface: tools.surface
        logExposure: tools.logExposure
      outputParameters:
      - type: object
        mapping: $.
    - name: request-decisions-query-exposure-history
      description: Request Decisions or Query Exposure History for Growth Experiments
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: memesio-growth.post
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-lifecycle-messaging-flow-config
      description: Get Lifecycle Messaging Flow Config and Recent Dispatch History
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: memesio-growth.get
      outputParameters:
      - type: object
        mapping: $.
    - name: preview-run-lifecycle-messaging-flows
      description: Preview/Run Lifecycle Messaging Flows (Activation, Resurrection, Upgrade)
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: memesio-growth.post
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-referral-credits-actor
      description: Get Referral Credits for Actor
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: memesio-growth.get
      with:
        actorId: tools.actorId
      outputParameters:
      - type: object
        mapping: $.
    - name: create-redeem-referral-invite-code
      description: Create or Redeem Referral Invite Code with Fraud Checks
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: memesio-growth.post
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-social-publish-gate-state
      description: Get Social Publish Gate State, Connected Accounts, and Recent Publishes
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: memesio-growth.get
      with:
        actorId: tools.actorId
        publishLimit: tools.publishLimit
      outputParameters:
      - type: object
        mapping: $.
    - name: connect-disconnect-social-accounts-and
      description: Connect/Disconnect Social Accounts and One-Click Publish (Phase-Gated)
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: memesio-growth.post
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: generate-retrieve-weekly-trend-driven
      description: Generate or Retrieve Weekly Trend-Driven Template Campaigns
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: memesio-growth.get
      with:
        weekStart: tools.weekStart
        limit: tools.limit
        publishedOnly: tools.publishedOnly
      outputParameters:
      - type: object
        mapping: $.
    - name: publish-weekly-trend-driven-template
      description: Publish Weekly Trend-Driven Template Campaigns for Marketing Ops
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: memesio-growth.post
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-viral-loop-trigger-definitions
      description: Get Viral Loop Trigger Definitions and Instrumentation Mapping
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: memesio-growth.get
      outputParameters:
      - type: object
        mapping: $.
    - name: get-weekly-meme-leaderboard
      description: Get Weekly Meme Leaderboard
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: memesio-growth.get
      with:
        weekStart: tools.weekStart
        limit: tools.limit
      outputParameters:
      - type: object
        mapping: $.
    - name: cast-weekly-meme-vote-deduped
      description: Cast Weekly Meme Vote (Deduped by Voter Hash)
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: memesio-growth.post
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: close-weekly-winner-record-manual
      description: Close Weekly Winner Record for Manual Payout Workflow
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: memesio-growth.post
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: admin-approval-social-unlock-and
      description: Admin Approval for Social Unlock and Quota Boost
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: memesio-growth.post
      with:
        unlockId: tools.unlockId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: submit-social-action-proof-x
      description: Submit Social Action Proof (X_follow) for Quota Boost Review
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: memesio-growth.post
      with:
        agentId: tools.agentId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-export-preset-catalog-tiktok
      description: Get Export Preset Catalog (TikTok, Reels, Shorts, MP4 Square) and Optional Watermark Decision Preview
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: memesio-growth.get
      with:
        planTier: tools.planTier
        presetId: tools.presetId
        container: tools.container
        bitrateKbps: tools.bitrateKbps
        watermarkEnabled: tools.watermarkEnabled
        watermarkText: tools.watermarkText
      outputParameters:
      - type: object
        mapping: $.
    - name: evaluate-export-settings-plan-tier
      description: Evaluate Export Settings with Plan-Tier Watermark Rules for TikTok/Reels/Shorts/MP4 Square Presets
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: memesio-growth.post
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.