Quests: credits and objectives

Use these fields to publish quests with objectives from another system or an AI agent. Every quest you create spends one quest credit of the owning account, and the credit's plan sets the longest the quest can run. Quests use the shared operations in Events, courses, content, quests and jobs: list, get, update and archive on /api/v1/quests, with the same scopes, owner selector, visibility rules, Idempotency-Key header and limits (30 quest creates per day, 128 KiB per request). To enroll participants and review evidence, see Participation workflows.

The examples read the key from HIVE_API_KEY. Some field names still say community or person; both identify accounts.

#Quest fields

The server owns maxQuestDays, questCreditSource and questCreditId; values you send for them are ignored. Responses show them in data together with questCreditPlan.

#Objectives

Objectives are stored as you send them. Each is an object:

#Quest credits

• Creating a quest spends one credit of the owning account (the community when you use the owner selector). The credit's length matches questCreditPlan.
• The account's monthly allowance is spent first: Swarm includes one 7-day and one 30-day credit per UTC calendar month, Royal Hive two of each. Unused monthly credits expire at month end. Credits bought in the app are spent after that. Worker Bee and Honey Bee accounts have no monthly allowance.
• With no credit left the request returns 403 forbidden (No 7-day quest credits left. Buy a quest credit to create this quest., or 30-day for bundle). A request that fails validation spends no credit.
• Archiving a quest does not refund its credit.
• questCreditPlan is read without regard to case. A missing value returns 400 (questCreditPlan is required: single (7-day) or bundle (30-day)) and an unknown one returns 400 (Quest credit plan not found: weekly).

#Schedule and duration

A credited quest needs a valid startsAt (Credited quests require a valid startsAt timestamp), and a supplied endsAt must be valid too (Quest endsAt must be a valid timestamp). The span from startsAt to endsAt cannot exceed the plan: 7 days for single and 30 days for bundle, with one hour of tolerance for daylight-saving changes (Quest duration cannot exceed 7 days for its quest credit plan). Because an omitted endsAt means 30 days, a single quest always needs an explicit endsAt within 7 days.

On PATCH, an omitted startsAt keeps the stored start; sending startsAt, including null, replaces it. The stored plan and maxQuestDays stay in force.

#Quests that have started

A quest is locked once its start time has passed or it has ended. A locked quest returns 409 conflict on PATCH (This quest has started and can no longer be edited.) and on DELETE (This quest has started and can no longer be cancelled.). A quest created with a startsAt in the past is therefore locked from the first request. Quests whose startsAt is not a valid timestamp stay editable and cancellable. Archiving a quest that is already archived returns 200 again, like every other kind.

#Create a quest

curl -X POST https://app.hive3.tech/api/v1/quests \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-post-quest-001" \
  -d '{"title":"Share Your First Post","description":"Post and comment in the feed.","questCreditPlan":"single","startsAt":"2030-03-01T00:00:00Z","endsAt":"2030-03-07T23:59:59Z","objectives":[{"id":"comments","type":"post_comments_created","name":"Comment on two posts","targetCount":2},{"id":"likes","type":"post_likes_given","name":"Like three posts","targetCount":3}]}'

const res = await fetch("https://app.hive3.tech/api/v1/quests", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIVE_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "first-post-quest-001",
  },
  body: JSON.stringify({
    title: "Share Your First Post",
    description: "Post and comment in the feed.",
    questCreditPlan: "single",
    startsAt: "2030-03-01T00:00:00Z",
    endsAt: "2030-03-07T23:59:59Z",
    objectives: [
      { id: "comments", type: "post_comments_created", name: "Comment on two posts", targetCount: 2 },
      { id: "likes", type: "post_likes_given", name: "Like three posts", targetCount: 3 },
    ],
  }),
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://app.hive3.tech/api/v1/quests",
    headers={
        "Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
        "Idempotency-Key": "first-post-quest-001",
    },
    json={
        "title": "Share Your First Post",
        "description": "Post and comment in the feed.",
        "questCreditPlan": "single",
        "startsAt": "2030-03-01T00:00:00Z",
        "endsAt": "2030-03-07T23:59:59Z",
        "objectives": [
            {"id": "comments", "type": "post_comments_created", "name": "Comment on two posts", "targetCount": 2},
            {"id": "likes", "type": "post_likes_given", "name": "Like three posts", "targetCount": 3},
        ],
    },
)
quest = res.json()["data"]

{
  "data": {
    "id": "quest_123",
    "type": "quest",
    "title": "Share Your First Post",
    "description": "Post and comment in the feed.",
    "status": "active",
    "visibility": "public",
    "autoEnroll": true,
    "badges": [],
    "credentials": [],
    "objectives": [
      { "id": "comments", "type": "post_comments_created", "name": "Comment on two posts", "targetCount": 2 },
      { "id": "likes", "type": "post_likes_given", "name": "Like three posts", "targetCount": 3 }
    ],
    "owner": { "type": "person", "personId": "account_123" },
    "data": {
      "title": "Share Your First Post",
      "description": "Post and comment in the feed.",
      "startsAt": "2030-03-01T00:00:00Z",
      "endsAt": "2030-03-07T23:59:59Z",
      "autoEnroll": true,
      "visibility": "public",
      "questCreditPlan": "single",
      "maxQuestDays": 7,
      "questCreditSource": "monthly"
    },
    "createdAt": 1767225600000,
    "updatedAt": 1767225600000
  }
}

#Update a quest

curl -X PATCH https://app.hive3.tech/api/v1/quests/quest_123 \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"Post, comment and like in the feed.","endsAt":"2030-03-06T23:59:59Z"}'