API overview

​

Base URL and sign-in

npx @colosseum-org/[email protected] login

npx @colosseum-org/[email protected] token | sed 's/^/Authorization: Bearer /' | curl -H "X-Copilot-Skill-Version: 2.0.3" --silent --show-error --include --header @- https://copilot.colosseum.com/api/v2/status

npx @colosseum-org/[email protected] token | sed 's/^/Authorization: Bearer /' | curl -H "X-Copilot-Skill-Version: 2.0.3" --silent --show-error --header @- \
  --header 'Content-Type: application/json' \
  --data '{"query":"privacy wallet for stablecoin users","limit":5}' \
  https://copilot.colosseum.com/api/v2/search/projects

​

Endpoints

​

Your own data

​

Projects

• Search. POST /search/projects ranks projects by similarity to your query. Results favor the closest matches; set diversify: true for more variety across hackathons and tracks. An empty query lists every project that matches your filters, newest first.
• Counting. With an empty query, totalFound is the exact number of matching projects. With a text query, totalFound only supports paging, so don’t treat it as a count. Check filtersApplied to see the filters that were used.
• Facets. Set includeFacets: true and list the facets you want in facets. The default list leaves out categories. Facets count everything that matches your filters and ignore the text query.
• Details. Search results leave out the summaries of each team’s code, pitch and demo. Fetch GET /projects/by-slug/:slug for those.
• Valid values. GET /filters lists hackathon slugs and start dates, prize track keys, submission label keys, accelerator batches, prize types, tags and research library sources.
• Prizes. award is winner, honorable_mention or null. filters.winnersOnly, isWinner, winnerCount and the winners totals exclude honorable mentions. Use filters.prizeTypes: ["HONORABLE_MENTION"] to find mentions separately; they carry prize.type: "HONORABLE_MENTION" with no amount, and they’re recognitions, not wins. Frontier had no tracks: its 25 TRACK_PRIZE awards named Winner are its top-25 awards, not track prizes.
• Tracks and labels. tracks lists the prize tracks a project entered, not the one it won. The track a project won is prize.trackName; to list a track’s winners, filter winnersOnly results by prize.trackName. Events without track prizes, including Frontier, return submission choices in labels. trackClassification is prize_tracks, submission_labels or ambiguous; ambiguous projects expose neither. Search with labelKeys from /filters.labels or the labels facet. Do not combine labelKeys and trackKeys; a trackKeys filter for an event without track prizes is rejected.
• Scores. With includeDiagnostics: true, the response shows how results were ranked. Compare scores only between results ranked the same way.

​

Categories

• filters.categoryKeys takes one to ten category keys and matches any of them. To cover an area, list its category keys.
• Filters, facets and POST /analyze count main categories only by default. Set includeSecondaryCategories: true to include second categories. Those counts can overlap, and the response then sets categoryCountsOverlap: true.
• For every category count in one request, call POST /analyze with dimensions: ["categories"] and topK: 43. Category facets also accept facetTopK: 43. Other dimensions and facets return at most 20 buckets.
• POST /compare doesn’t accept categories.

​

Technologies

{
  "hackathonSlugs": ["radar", "breakout"],
  "winnersOnly": true,
  "includeHonorableMentions": false,
  "categoryKeys": ["stablecoin-rails"]
}

• Counts: { "technology": {...}, "cohort": {...} } returns how many projects are tagged with it, overall and per hackathon.
• Used together: same body plus optional topK (1 to 50, default 10). Returns the technologies most often used alongside it.
• Trends: same body as counts. Returns usage per hackathon, in date order.
• Top: optional cohort, technologyCategory and topK. Returns the most-used technologies. Leave out technologyCategory to rank across all seven.

​

Research library

• Search. POST /search/archives returns snippets of up to 240 characters and pages up to offset 50. totalFound supports paging and isn’t an exact count. totalMatched counts text matches only. searchTier shows which search method found the results. maxDocsPerSource: 0 removes the per-source cap.
• Reading. GET /archives/:documentId returns a document a page at a time. maxChars defaults to 8,000 and can be 200 to 20,000.
• Excerpts. Some licensed sources are available only as excerpts. Their responses have isExcerpt: true (and restricted: true), at most 1,000 characters in total, an excerptNote, and a url to the full piece on the publisher’s site.
• Withdrawn documents return 404 NOT_FOUND.

​

Builder tools

​

Program FAQs

• program is optional: hackathon, eternal, accelerator or stamp.
• q is optional, 2 to 200 characters. It’s a keyword search that ranks matches in the question above matches in the answer. No matches returns an empty faqs list.
• GET /faqs/:program/:id returns one FAQ. Unknown IDs return 404.

​

Sharing questions and answers

• Requirements: a sign-in with sharing turned on and the telemetry:write scope. Without both, the request gets 403 INSUFFICIENT_SCOPE. GET /status shows sessionSharingEnabled.
• Body: sessionId (a UUID) and messages: 2 to 100 objects with role (user or assistant) and content (1 to 20,000 characters), with at least one of each role. The messages array can be up to 100,000 characters in total.
• New conversation: 201 with { saved: true, expiresAt }. Conversations are kept for 12 months.
• Same sessionId again: 200. Adding messages to the end returns saved: true. Otherwise it returns saved: false with a reason: unchanged, not_newer (the upload is shorter than the saved copy, or its earlier messages differ) or expired. Updates don’t change the expiry date.

​

Feedback and source suggestions

​

Scopes

​

Limits

​

Errors