API Documentation
Scout The Bot API - current, clear, and ready to build.
Use the API to pull team descriptions, automate scouting tools, and integrate support + manual lookups.
Read-first access
Session-secured writes
FTC API proxy
Base URL
All requests are same-origin. Use your deployed site domain.
Access rules
API keys are for data access. Writes are locked behind team or admin sessions.
- Send a key with the
x-api-keyheader,apiKeyquery param, orapi_keycookie. - API keys are read-only and can fetch team descriptions, stats, images, and manual status.
- Any write to team data, images, notes, or passwords requires a logged-in session.
- Public write endpoints are limited to support tickets, manual chat, alliance requests, and predictions.
Need edit access? Use the team login flow or request admin access.
Request API access
To get an API key for external integrations, reach out to support.
Email
scoutthebots@gmail.com
Include your team number, use case, and expected request volume.
Quickstart
Set your base URL, then call the team data endpoint.
cURL
curl -H "x-api-key: YOUR_KEY" "{baseUrl}/api/team/data/12345"API key auth
All /api calls require a key. Browser sessions on scoutthebots.org receive a public key cookie automatically.
x-api-key: YOUR_KEYFor server-to-server use, set
x-api-key on every request.Sessions for writes
Team and admin sessions unlock write access. Use the auth endpoints to create a session cookie.
- Team login:
/api/auth/initthen/api/auth/verify. - Admin login:
/api/admin/login. - Writes without a session return
403.
Error handling
Errors always return JSON with an error string. Use status codes to branch logic.
{
"error": "Invalid or inactive API key"
}If Gemini returns an error, the response includes
aiError and a safe fallback message.Endpoint reference
Updated for 2025-2026Expand an endpoint to view auth requirements, payloads, and response notes.
Core data (read)
GET /api/team/data/:teamNumber Team descriptions + canEdit flag
Params: teamNumber (path)
GET {baseUrl}/api/team/data/12345Returns: autoDesc, teleopDesc, strategyDesc, partnerDesc, canEdit.
GET /api/images/:teamNumber Image list for a team
Params: teamNumber (path)
Returns: Array of image records with
filename and type.GET /api/stats/overview Public site metrics
Returns: visits, team_views, teams_registered, prediction_accuracy, and more.
Alias: /api/site/overview (worker deployments).
Authentication & team sessions
POST /api/auth/init Start team auth challenge
Body: { "teamNumber": 12345 }
POST /api/auth/verify Verify challenge + start session
Body: { "teamNumber": 12345, "answer": "..." }
GET /api/auth/status Check session
Returns: { loggedIn, teamNumber }
POST /api/auth/logout Clear team session
POST /api/team/password Set team password
Body: { "password": "new-password" }
POST /api/team/update Update team descriptions
Body: { "auto": "...", "teleop": "...", "strategy": "...", "partner": "..." }
POST /api/upload Upload team images
Body: multipart form with
image, teamNumber, and type.GET /api/notes List private notes
GET /api/notes/:subjectTeam Read a private note
Params: subjectTeam (path)
POST /api/notes Create or update a note
Body: { "subjectTeamNumber": 12345, "note": "..." }
Support & reports
POST /api/support/create Open a support ticket
Body: { message, teamNumber?, contactName?, contactEmail?, subject?, imageFilename? }
POST /api/support/upload Upload support images
Body: multipart form with
image.GET /api/support/threads List ticket threads
Auth: Send
x-support-token header or ?token=....GET /api/support/thread/:id Get thread + messages
POST /api/support/thread/:id/message Reply to a thread
Body: { "message": "...", "imageFilename": "..." }
POST /api/report Report an issue
Body: { "teamNumber": 12345, "issue": "..." }
Manual & AI
GET /api/manual/status Manual metadata
Returns: sourceUrl, fetchedAt, pages, chunkCount.
POST /api/manual/chat Ask the game manual
Body: { "question": "...", "history": [], "aiEnabled": true }
Returns: answer, aiError, citations, manual metadata.
Strategy & predictions
POST /api/alliance-selection Alliance partner suggestions
Body: { "captainTeam": "...", "teams": [...] }
POST /api/predictions/batch Submit match prediction outcomes
Body: { "predictions": [ { season, eventCode, matchKey, predictedWinner, actualWinner } ] }
Analytics
POST /api/site/visit Track a site visit
Notes: Used by the client to track visits. Accepts GET or POST.
Admin
POST /api/admin/login Start admin session
Body: { "password": "..." }
POST /api/admin/logout Clear admin session
GET /api/admin/stats Admin dashboard stats
GET /api/admin/teams Team registry
POST /api/admin/teams/:teamNumber/reset-password Reset team password
GET /api/admin/api-keys List API keys
POST /api/admin/api-keys Create API key
Body: { label, ownerTeamNumber?, contactEmail? }
DELETE /api/admin/api-keys/:id Delete API key
GET /api/admin/support/threads All support threads
GET /api/admin/support/threads/:id Thread details
POST /api/admin/support/threads/:id/message Reply to thread
Body: { "message": "..." }
POST /api/admin/support/threads/:id/status Update status
Body: { "status": "open|closed" }
POST /api/admin/support/threads/:id/delete Delete thread (legacy)
DELETE /api/admin/support/threads/:id Delete thread
GET /api/admin/reports Reported issues
POST /api/admin/reports/:id/close Close report
DELETE /api/admin/image/:id Remove an image
FTC Scout proxy
PROXY /v2.0/* Pass-through to FTC Scout API
Notes: Same path, headers, and response as FTC Scout.
Need help?
Reach out any time for onboarding, higher limits, or integration questions.