API & Integrations

Three surfaces, one header (X-API-Key). Partner write keys you mint yourself: one user key on your profile (or Dashboard → Keys) — the secret starts with your Tessera username — or a team key (Team → Settings). Event and read-feed keys are still issued by Tessera.

POST  https://api.tesserapp.org/events/v1/webhooks
GET   https://api.tesserapp.org/events/v1/feed
GET   https://api.tesserapp.org/provider/ping
GET   https://api.tesserapp.org/provider/communities
GET   https://api.tesserapp.org/provider/communities?x={handle}
GET   https://api.tesserapp.org/provider/raffles
GET   https://api.tesserapp.org/provider/raffles/{raffleId}
GET   https://api.tesserapp.org/provider/raffles/{raffleId}/winners

Authentication

Send your key on every request in the X-API-Key header (Authorization: Bearer <key> works too). Event keys, read-feed keys, and partner keys are separate — ask for the one you need.

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.tesserapp.org/provider/raffles?status=active&limit=100"

GET /provider/ping and GET /events/v1/ping are unauthenticated — connectivity only.

Communities

Public team-page stats. Same read key as the raffle feed. A daily pass is enough. The cap is 60 requests a minute.

Look up one community by its project X:

GET /provider/communities?x=joinsyndicate_

x can be a handle, @handle, or an x.com / twitter.com profile URL. One team per handle. No match is 404. A value that is not a handle is 400.

Walk every community when you do not have the handle yet. Oldest first. cursor is the nextCursor from the previous page. limit defaults to 50 and stops at 100.

GET /provider/communities?limit=50

The body includes "source": "tessera".

Live events

HTTPS webhooks. You register a URL; Tessera POSTs JSON the moment a raffle opens or a project first appears. No websocket. If you cannot expose a URL, poll GET /events/v1/feed.

A raffle for a new project fires both events. Treat them as independent POSTs — delivery order is not guaranteed.

curl -X POST https://api.tesserapp.org/events/v1/webhooks \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-bot.example/tessera","events":["raffle.live","project.added"]}'

import crypto from 'node:crypto'
 
function ok(rawBody, secret, header) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')
  return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected))
}

Body

{
  "id": "evt_…",
  "type": "raffle.live",
  "createdAt": "2026-09-16T18:00:00Z",
  "data": {}
}

raffle.live data

project.added data

Poll instead

GET /events/v1/feed?since={ISO}&type=raffle.live&limit=50 — same envelopes, oldest first, last ~200 events. Use since as the previous createdAt. Still needs X-API-Key.

Read feed

Poll when you need the full raffle list or winners. For “it just went live”, use Live events above.

List raffles

GET /provider/raffles — every raffle on Tessera, newest first, paginated.

Raffle fields

Hosted by, hosted for, project

The raffle page shows three identities. GET /provider/raffles and GET /provider/raffles/{id|slug} use the same three.

On Farmerz DAO x Ascendant, Hosted by is SUNNIKA (runner), Hosted for is Farmerz Club (hostedFor), and Project is Ascendants @ascendantsgames (project).

project is null when the raffle has no project X. createdBy, managedBy, and drawnBy still mirror runner.

Runner identity

Every raffle carries the actual person who runs it, keyed the way integrations need it:

createdBy, managedBy and drawnBy mirror runner — Tessera has a single raffle role (the creator). drawnBy is null until winners are drawn.

Requirements

The requirements array is pass-through from Tessera's own model — map what you need:

Winners

GET /provider/raffles/{raffleId} (or the URL slug) returns the raffle plus:

Errors

Rate guidance: paginate with limit ≤ 200 and walk offset; prefer updated_since for incremental polling.

Partner write API

For bots that create raffles and pull winners after draw (not the CollabOS read feed). Auth is X-API-Key.

Two kinds of keys — mint them in the app, secret shown once:

A user key on Sanctuary does not fail with a silent 404 on another community you belong to — it works there too. A team key for Sanctuary returns 403 if you send a different teamId. A team that does not exist is 404. A missing route is 404 Not Found.

GET   https://api.tesserapp.org/partner/v1/ping
GET   https://api.tesserapp.org/partner/v1/teams
GET   https://api.tesserapp.org/partner/v1/templates?teamId=
POST  https://api.tesserapp.org/partner/v1/raffles
GET   https://api.tesserapp.org/partner/v1/raffles/{id|slug}
GET   https://api.tesserapp.org/partner/v1/raffles/{id|slug}/winners
GET   https://api.tesserapp.org/partner/v1/raffles/{id|slug}/winners.csv

Mint / list / revoke (session cookie, same as the site):

GET/POST/DELETE  https://api.tesserapp.org/user/api-keys
GET/POST/DELETE  https://api.tesserapp.org/teams/{teamId}/api-keys

Create

POST /partner/v1/raffles — same fields as the site create form.

Follow handles do not have to be looked up on X before create. GET /partner/v1/templates returns targetUserId on each twitter_follow row when Tessera can see the profile. GET /partner/v1/x/lookup?handle= returns { found, handle, userId } with status 200. found: false means that profile page is gone. An X API body of User not found is not a reason to skip the community — post the raffle with the handle, or with targetUserId when it is set. Create still saves the follow if that id is missing.

Status

GET /partner/v1/raffles/{id} is safe to poll anytime. It returns status (active / ended), endsAt, drawn (bool), announcedAt, entryCount. No winner list. No entries.

Winners

GET …/winners and …/winners.csv return the drawn Winner table only.

• While the raffle is live: 409 { "detail": { "ready": false, "reason": "not_ended" } }
• Ended, but winners are still pending (pre-draw) or there are none: 409 not_drawn
• A short draw still returns. If the raffle ended and every saved winner is confirmed, you get that list even when fewer people won than winnerCount
• Never returns in-progress entrants as winners
• The public read feed (GET /provider/raffles/{id}/winners) stays empty until winners are announced or the host marks them public. Partner winners do not wait for that announce
• wallet is the payout address for the raffle’s current requiredWalletType. If the chain changes after people enter (EVM → SOL), wallet is the SOL address, not the 0x saved at entry. The address they entered is kept only when it still matches that chain.
• Each winner also includes the profile wallets: walletAddress (EVM), solWalletAddress, btcWalletAddress, zecWalletAddress, nearWalletAddress, suiWalletAddress, xmrWalletAddress. The read feed (GET /provider/raffles/{id}/winners) uses the same fields. Sui addresses are 0x plus 64 hex. Monero addresses are mainnet, start with 4 or 8, and keep their original case.
• The JSON body includes requiredWalletType.

CSV columns: rank, username, discordId, xHandle, wallet, tierName, status, then the profile wallet columns (walletAddress, solWalletAddress, btcWalletAddress, zecWalletAddress, nearWalletAddress, suiWalletAddress, xmrWalletAddress). wallet is the payout column.

Next