Airaa
Sign up
Docs/API

Campaigns

List one community's campaigns, and read any one of them in full.

2 endpoints, generated from openapi.yaml. New to the API? Start with the Overview.

List one community's campaigns, then read any one of them in full. get_campaign_details covers both bounty and video campaigns. Its detailVariant field tells you which shape came back.

Base URL
https://app.airaa.xyz

Every tool is a POST to /api/ai/mcp/tools/{tool}/execute with arguments wrapped in an args object, authorised with Authorization: Bearer airaa_<key>.

get_project_campaigns

List campaigns in a community

POST/api/ai/mcp/tools/get_project_campaigns/execute

What campaigns are running in this community?

One community's campaigns, filterable by status and by type. projectId is required: this lists a single community's campaigns, not every campaign your key can reach. Campaigns hidden in the dashboard are excluded.

This endpoint paginates with a counts object (live, draft and ended totals plus total spent) rather than the metadata envelope the other paginated tools return.

Arguments

statusByobject

Narrow to one campaign status.

campaignTypeobject

Narrow to one campaign family. instant_tasks is the bounty campaigns; clipping and UGC are the two video campaign types.

projectIdstringrequired

The community id, from list_manageable_projects. Lists this community only.

pageinteger

Page number, 1-indexed

min 1 · defaults to 1
limitinteger

Items per page, max 100

1 to 100 · defaults to 10

Returns

Fields inside result.

campaignsarray of CampaignListItem
countsCampaignCounts

Aggregate totals. get_project_campaigns returns this instead of a metadata object.

projectsarray of object

Errors

  • 400An argument is missing or failed validation; the message names the field. Also returned when a required projectId is omitted.
  • 401The key is missing or not valid.
  • 403The key is valid but you do not administer that community.
  • 404No such tool, or no campaign with that id.
  • 429Too many requests. Tool execution is limited to 120 calls per minute per user.

Request

curl -X POST https://app.airaa.xyz/api/ai/mcp/tools/get_project_campaigns/execute \
  -H "Authorization: Bearer $AIRAA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"args": {"projectId": "3f2a9c7e-1b84-4d5a-9e60-7c1af2b83d41","statusBy": "LIVE","limit": 10}}'

Response

Note the counts object where other endpoints return metadata.

200
{
  "result": {
    "campaigns": [
      {
        "id": "a7d2f61c-08b5-4e3a-9c14-5f8b73d20e69",
        "title": "Launch week clips",
        "status": "LIVE",
        "campaignType": "clipping",
        "taskTypes": [
          "CLIP_X",
          "CLIP_TIKTOK"
        ],
        "totalPool": "12000.00",
        "remainingPool": "7420.15",
        "usedBudget": "4579.85",
        "platform": [
          {
            "id": "f0a4c927-51d8-4b63-9a72-e8d1c3406b5f",
            "name": "TikTok",
            "enabled": true
          },
          {
            "id": "9d6b23e1-7c40-4f85-b91a-04e7f2d85c63",
            "name": "Instagram",
            "enabled": true
          }
        ],
        "payoutType": "FCFS",
        "tokenType": "ERC20",
        "tokenSymbol": "USDC",
        "completedUsersCount": 38,
        "incompletedUsersCount": 6,
        "hasCounterOffer": false,
        "approvedClipsCount": 112,
        "impressions": 4820000,
        "pendingReviewsCount": 9,
        "project": {
          "id": "3f2a9c7e-1b84-4d5a-9e60-7c1af2b83d41",
          "name": "Lumen Labs",
          "logo": "https://cdn.airaa.xyz/projects/lumenlabs/logo.png"
        },
        "createdAt": "2026-08-04T09:12:44.000Z"
      },
      {
        "id": "c14e7b90-5a23-4f81-b6d7-90e3ac215f42",
        "title": "Quote the launch thread",
        "status": "LIVE",
        "campaignType": "social",
        "taskTypes": [
          "QUOTE",
          "REPLY"
        ],
        "totalPool": "2500.00",
        "remainingPool": "1180.00",
        "usedBudget": "1320.00",
        "platform": [
          {
            "id": "6e2c81b4-3f97-40da-85c1-b70d924ef3a8",
            "name": "Twitter/X",
            "enabled": true
          }
        ],
        "payoutType": "OFFERS",
        "tokenType": "ERC20",
        "tokenSymbol": "USDC",
        "completedUsersCount": 44,
        "incompletedUsersCount": 12,
        "hasCounterOffer": true,
        "approvedClipsCount": 0,
        "impressions": 612400,
        "pendingReviewsCount": 3,
        "project": {
          "id": "3f2a9c7e-1b84-4d5a-9e60-7c1af2b83d41",
          "name": "Lumen Labs",
          "logo": "https://cdn.airaa.xyz/projects/lumenlabs/logo.png"
        },
        "createdAt": "2026-07-21T15:02:10.000Z"
      }
    ],
    "counts": {
      "live": 2,
      "draft": 1,
      "ended": 8,
      "spent": 5899.85
    },
    "projects": [
      {
        "id": "3f2a9c7e-1b84-4d5a-9e60-7c1af2b83d41",
        "name": "Lumen Labs",
        "logo": "https://cdn.airaa.xyz/projects/lumenlabs/logo.png",
        "role": "ADMIN"
      }
    ]
  }
}

get_campaign_details

Get campaign details

POST/api/ai/mcp/tools/get_campaign_details/execute

What are this campaign's settings, budget and results?

Read detailVariant first. The same call returns two different bodies: clipping_owner for a video campaign that has left draft, and social_owner for a bounty campaign and for any campaign still in DRAFT.

Both variants carry campaign, project, stats and budget. The social_owner variant populates tasks and leaves clippingOwner null. The clipping_owner variant fills clippingOwner with the analytics payload: submission counts, reach split into initial and current, per-platform payout rules, and bonus milestones.

Arguments

projectCampaignIdstringrequired

The campaign id, from get_project_campaigns. Works for a bounty or a video campaign.

Returns

Fields inside result.

campaignTypeenum
socialclippingugc
detailVariantenum

social_owner for bounty campaigns and any draft; clipping_owner for non-draft video campaigns. Tells you which of the two shapes came back.

social_ownerclipping_owner
campaignobject
projectobject
statsobject
budgetBudget
tasksarray of object
clippingOwnerClippingOwnerDetail | null
campaignCommissioninteger | null

Platform commission percentage for this campaign.

draftConfigobject | null
eligibilityProjectobject | null

Errors

  • 400An argument is missing or failed validation; the message names the field. Also returned when a required projectId is omitted.
  • 401The key is missing or not valid.
  • 403The key is valid but you do not administer that community.
  • 404No such tool, or no campaign with that id.
  • 429Too many requests. Tool execution is limited to 120 calls per minute per user.

Request

curl -X POST https://app.airaa.xyz/api/ai/mcp/tools/get_campaign_details/execute \
  -H "Authorization: Bearer $AIRAA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"args": {"projectCampaignId": "a7d2f61c-08b5-4e3a-9c14-5f8b73d20e69"}}'

Response

A video campaign past draft. clippingOwner is populated, tasks is empty.

clipping owner
{
  "result": {
    "campaignType": "clipping",
    "detailVariant": "clipping_owner",
    "campaign": {
      "id": "a7d2f61c-08b5-4e3a-9c14-5f8b73d20e69",
      "projectId": "3f2a9c7e-1b84-4d5a-9e60-7c1af2b83d41",
      "title": "Launch week clips",
      "status": "LIVE",
      "type": "clipping",
      "imageUrl": "https://cdn.airaa.xyz/campaigns/launch-week/cover.png",
      "startDate": "2026-08-05T00:00:00.000Z",
      "endDate": "2026-09-05T00:00:00.000Z",
      "createdAt": "2026-08-04T09:12:44.000Z",
      "approvalMode": "MANUAL",
      "needsDraft": false,
      "userEligibilityCriteria": {
        "minFollowers": 1000
      }
    },
    "project": {
      "id": "3f2a9c7e-1b84-4d5a-9e60-7c1af2b83d41",
      "name": "Lumen Labs",
      "slug": "lumenlabs",
      "logo": "https://cdn.airaa.xyz/projects/lumenlabs/logo.png"
    },
    "stats": {
      "creators": 44,
      "reach": 4820000,
      "likes": 291400,
      "quotes": 0,
      "post": 112
    },
    "budget": {
      "totalPool": "12000.00",
      "remainingPool": "7420.15",
      "tokenType": "ERC20",
      "tokenSymbol": "USDC",
      "tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "chainId": "8453",
      "decimals": 6
    },
    "tasks": [],
    "clippingOwner": {
      "demographicsRequired": true,
      "demographicsAudienceRule": "60% US or UK",
      "eligibilitySummary": {
        "mode": "open",
        "guild": null
      },
      "overview": {
        "creatorsCount": 44,
        "totalSubmissionsCount": 137,
        "submissionsCount": 128,
        "pendingSubmissionsCount": 9,
        "approvedSubmissionsCount": 112,
        "rejectedSubmissionsCount": 7,
        "paidSubmissionsCount": 98,
        "reach": 4820000,
        "currentReach": 4913200,
        "initialReach": 93200,
        "likes": 291400,
        "comments": 18720
      },
      "budget": {
        "label": "Campaign budget",
        "totalPool": "12000.00",
        "remainingPool": "7420.15",
        "usedBudget": "4579.85",
        "tokenType": "ERC20",
        "tokenSymbol": "USDC"
      },
      "tasksTab": {
        "requirements": {
          "guidelines": "Hook in the first two seconds. No captions over the logo.",
          "hashtags": [
            "lumenlabs"
          ],
          "mentions": [
            "@lumenlabs"
          ],
          "urls": [
            "https://lumenlabs.com"
          ]
        },
        "tasks": [
          {
            "taskId": "7b3e19a2-c845-4d70-9e16-a2f5c80b31d4",
            "platformId": "f0a4c927-51d8-4b63-9a72-e8d1c3406b5f",
            "platformName": "TikTok",
            "platformSlug": "tiktok",
            "type": "CLIP",
            "submissionRequirements": {
              "guidelines": "Hook in the first two seconds.",
              "hashtags": {
                "values": [
                  "lumenlabs"
                ],
                "isEnabled": true,
                "requireAll": true
              },
              "mentions": {
                "values": [
                  "@lumenlabs"
                ],
                "isEnabled": true,
                "requireAll": false
              },
              "urls": {
                "values": [],
                "isEnabled": false,
                "requireAll": false
              }
            },
            "submissionCounts": {
              "total": 82,
              "pending": 5,
              "approved": 71,
              "rejected": 6,
              "paid": 63,
              "nonRejected": 76
            }
          }
        ]
      },
      "settingsTab": {
        "userEligibilityCriteria": {
          "minFollowers": 1000
        },
        "platformPayouts": [
          {
            "taskId": "7b3e19a2-c845-4d70-9e16-a2f5c80b31d4",
            "platformId": "f0a4c927-51d8-4b63-9a72-e8d1c3406b5f",
            "platformName": "TikTok",
            "platformSlug": "tiktok",
            "claimType": "FCFS",
            "payoutLogic": "FORMULA",
            "cpm": 1.4,
            "fixedPayout": null,
            "minViews": 1000,
            "maxPayoutPerClip": 250,
            "bonusRanges": [
              {
                "views": 100000,
                "amount": 50
              },
              {
                "views": 500000,
                "amount": 300
              }
            ],
            "tokenType": "ERC20",
            "tokenSymbol": "USDC"
          }
        ]
      }
    },
    "campaignCommission": 10,
    "draftConfig": null,
    "eligibilityProject": null
  }
}

A bounty campaign. tasks is populated, clippingOwner is null.

social owner
{
  "result": {
    "campaignType": "social",
    "detailVariant": "social_owner",
    "campaign": {
      "id": "c14e7b90-5a23-4f81-b6d7-90e3ac215f42",
      "projectId": "3f2a9c7e-1b84-4d5a-9e60-7c1af2b83d41",
      "title": "Quote the launch thread",
      "status": "LIVE",
      "type": "social",
      "imageUrl": null,
      "startDate": "2026-07-22T00:00:00.000Z",
      "endDate": null,
      "createdAt": "2026-07-21T15:02:10.000Z",
      "approvalMode": "AI",
      "needsDraft": false,
      "userEligibilityCriteria": {
        "minFollowers": 500
      }
    },
    "project": {
      "id": "3f2a9c7e-1b84-4d5a-9e60-7c1af2b83d41",
      "name": "Lumen Labs",
      "slug": "lumenlabs",
      "logo": "https://cdn.airaa.xyz/projects/lumenlabs/logo.png"
    },
    "stats": {
      "creators": 56,
      "reach": 612400,
      "likes": 21840,
      "quotes": 44,
      "post": 44
    },
    "budget": {
      "totalPool": "2500.00",
      "remainingPool": "1180.00",
      "tokenType": "ERC20",
      "tokenSymbol": "USDC",
      "tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "chainId": "8453",
      "decimals": 6
    },
    "tasks": [
      {
        "taskId": "48f0d2b7-6a19-4c53-b8e0-71c9a35d6f42",
        "type": "QUOTE",
        "platformName": "Twitter/X",
        "tokenReward": "20.00",
        "claimedCount": 56,
        "approvedCount": 44
      }
    ],
    "clippingOwner": null,
    "campaignCommission": 10,
    "draftConfig": null,
    "eligibilityProject": null
  }
}