Back to API Overview

Challenges API

Builder challenges: read the open ones and their entries; enter, withdraw or comment, and see your entry’s stats and share kit.

11 endpoints

Endpoints

POST
/api/v1/challenge/publicListActive

List the builder challenges anyone can see: those open now (taking entries, or voting) and the 12 most recently closed. No params. Returns { active: [{ id, slug, title, brief, theme, heroImageUrl, status (LIVE = taking entries, VOTING), cycleType, prizeType, prizeCashCents, prizeMessageCredits, submissionsOpenAt, submissionsCloseAt, votingOpenAt, votingCloseAt, _count: { submissions } }], recent: [{ id, slug, title, theme, prizeType, prizeCashCents, prizeMessageCredits, votingCloseAt, winnerSubmissionId }] }. Only reads.

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/challenge/publicListActive \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{}'
POST
/api/v1/challenge/publicGetById

Read one builder challenge by its id: brief, rules, prize and dates. Params: id. Returns { id, slug, title, brief, theme, heroImageUrl, rulesMarkdown, status, cycleType, prizeType, prizeCashCents, prizeMessageCredits, submissionsOpenAt, submissionsCloseAt, votingOpenAt, votingCloseAt, revealTallyAt, winnerSubmissionId }; a challenge that is not published answers "Challenge not found". Only reads.

Parameters

idstringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/challenge/publicGetById \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example"
}'
POST
/api/v1/challenge/publicGetBySlug

Read one builder challenge by its slug with a page of its public entries. Params: slug, limit? (1-100), cursor? (nextCursor of the page before). Returns { challenge (as challenge_publicGetById, plus _count.submissions), tallyRevealed, submissions: [{ id, tagline, thumbnailR2Key, utmSlug, status, createdAt, builderUser { id, name }, project { id, name, slug }, _count { votes, comments }, rank, finalScore }], nextCursor }; rank, finalScore and _count.votes stay null until the tally is revealed; then the entries come in rank order across pages, newest first before. A cursor that is not an entry of this list is refused. Only reads.

Parameters

slugstringrequired
limitinteger
cursorstring

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/challenge/publicGetBySlug \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "slug": "example",
  "limit": {},
  "cursor": "example"
}'
POST
/api/v1/challenge/publicGetSubmission

Read one public challenge entry with its newest shown comments. Params: id (an entry id). Returns { submission: { id, tagline, thumbnailR2Key, utmSlug, status, createdAt, builderUser, project, challenge, _count (votes null until the tally is revealed) }, comments }; an entry that is not public answers "Submission not found". Only reads.

Parameters

idstringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/challenge/publicGetSubmission \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example"
}'
POST
/api/v1/challenge/builderHub

List the builder challenges open now and the person's own 20 newest entries. No params. Returns { active: [{ id, slug, title, brief, theme, status, cycleType, prizeCashCents, prizeMessageCredits, submissionsOpenAt, submissionsCloseAt, votingOpenAt, votingCloseAt }], mySubmissions: [{ id, tagline, status, createdAt, challenge { id, slug, title, status }, project { id, name }, _count { votes, clicks (signups), comments, shares (verified) } }] }. As the person, on their own account only (refused while working in another workspace); another person's entry answers "Submission not found". Only reads.

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/challenge/builderHub \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{}'
POST
/api/v1/challenge/builderGetMySubmissionStats

Read one of the person's own challenge entries with its numbers. Params: submissionId. Returns { submission: { id, tagline, status, demoVideoUrl, utmSlug, createdAt, challenge { id, slug, title, status, votingCloseAt }, project { id, name, slug } }, funnel { clicks, signups, conversionRate }, engagement { votes, comments, verifiedShares }, score (newest computed: { computedAt, upvotes, utmSignups, verifiedShares, comments, finalScore, rank }, or null) }. As the person, on their own account only (refused while working in another workspace); another person's entry answers "Submission not found". Only reads.

Parameters

submissionIdstringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/challenge/builderGetMySubmissionStats \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "submissionId": "example"
}'
POST
/api/v1/challenge/builderGetShareKit

Read the share kit of one of the person's own challenge entries: its tracked short link, hashtag, preview image and draft posts. Params: submissionId. Returns { shortUrl, hashtag, ogImageUrl, drafts { x, linkedin, generic } }. Posts nothing. As the person, on their own account only (refused while working in another workspace); another person's entry answers "Submission not found". Only reads.

Parameters

submissionIdstringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/challenge/builderGetShareKit \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "submissionId": "example"
}'
POST
/api/v1/challenge/builderSubmit

Enter one of the person's own published sites in a builder challenge that is taking entries, as that person. Params: challengeId, projectId (a published site of the person's own account), tagline (5-140 characters), demoVideoUrl? (an http or https link). Returns { id, shortUrl, hashtag }; the person is sent a confirmation email. One entry per person per challenge (a second answers that they already entered). Refused when entries are closed, or the site is not theirs or not published (publish it first). On their own account only. Voting is the person's own click on the challenge page in the dashboard: the AI never votes, so send the person there to vote.

Parameters

challengeIdstringrequired
projectIdstringrequired
taglinestringrequired
demoVideoUrlstringnull

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/challenge/builderSubmit \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "challengeId": "example",
  "projectId": "example",
  "tagline": "example"
}'
POST
/api/v1/challenge/builderWithdraw

Withdraw one of the person's own challenge entries, only while the challenge is taking entries. Params: submissionId. Returns { id, status }. Cannot be undone: the person can never enter that challenge again. As the person, on their own account only (refused while working in another workspace); another person's entry answers "Submission not found". Act only on what the person named or picked.

Parameters

submissionIdstringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/challenge/builderWithdraw \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "submissionId": "example"
}'
POST
/api/v1/challenge/builderComment

Comment on a challenge entry, as the person. Params: submissionId, body (2-500 characters). Returns { id, body, createdAt }. Refused when the person's account is less than 7 days old; an entry that is not public answers "Submission not found". On their own account only. Voting is the person's own click on the challenge page in the dashboard: the AI never votes, so send the person there to vote.

Parameters

submissionIdstringrequired
bodystringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/challenge/builderComment \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "submissionId": "example",
  "body": "example"
}'
POST
/api/v1/challenge/builderSubmitSharePost

Record a social post the person made about their own challenge entry, so it can be checked and count as a verified share. Params: submissionId, platform (X, LINKEDIN, TIKTOK, YOUTUBE or OTHER), postUrl (an http or https link; the same link once per entry). Returns { id, platform, postUrl, verified (false until checked), createdAt }. Posts nothing. As the person, on their own account only (refused while working in another workspace); another person's entry answers "Submission not found". Voting is the person's own click on the challenge page in the dashboard: the AI never votes, so send the person there to vote.

Parameters

submissionIdstringrequired
platformstringrequired

Allowed values: X, LINKEDIN, TIKTOK, YOUTUBE, OTHER

postUrlstringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/challenge/builderSubmitSharePost \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "submissionId": "example",
  "platform": "example",
  "postUrl": "example"
}'