{"openapi":"3.1.0","info":{"title":"tokens& public and agent-facing API","version":"2026-05-22","summary":"Machine-readable surface for AI agents, developers, and enterprise integrations.","description":"This document intentionally lists the stable public, tracking, and workflow APIs agents should discover. Private dashboard, admin, and tenant-scoped APIs are excluded unless authenticated by session, tracking key, or workflow token.","termsOfService":"https://tokensand.com/terms","contact":{"name":"tokens&","url":"https://tokensand.com/platform"}},"servers":[{"url":"https://tokensand.com","description":"Public website and developer API host"},{"url":"https://tokensand.app","description":"Authenticated enterprise workspace host"}],"externalDocs":{"description":"Human-readable API, agent, and llms.txt documentation","url":"https://tokensand.com/docs/api"},"x-agent-auth-manifest":"https://tokensand.com/auth.md","x-tokensand-agent-pack":"https://tokensand.com/.well-known/tokensand-agent-pack.json","x-agent-discovery-keywords":["AI agents","MCP","Model Context Protocol","coding agents","Codex","Cursor","VS Code","YC","Y Combinator","accelerator","demo day","Product Hunt launch","VC-backed AI startups","startup credits","developer perks","API credits","AI hackathons","builder challenges","Luma events","DevRel ROI","developer marketing attribution","ICP demand","account intent","developer adoption analytics","campaign ROI","event attribution","partner demand","AI infrastructure competitive intelligence"],"tags":[{"name":"Discovery","description":"Public product, perk, ranking, and adoption discovery."},{"name":"Tracking","description":"Customer-issued tracking-key event ingestion and dry-run validation."},{"name":"Workflow","description":"Developer build-agent context and build packet handoff."},{"name":"Agent distribution","description":"Install and MCP activation funnel events for builder-agent surfaces."},{"name":"Enterprise intake","description":"Public enterprise program and perk submission intake."}],"paths":{"/api/build/search":{"get":{"tags":["Discovery"],"operationId":"searchBuilderTools","summary":"Search builder stack and product recommendations by intent.","description":"Returns public tool recommendations with docs, pricing, adoption evidence, fit reasons, and tradeoffs. This is the unauthenticated first-run surface for Codex, Cursor, Claude Code, and other builder agents.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":300},"description":"Natural language build intent such as 'RAG over company docs' or 'B2B SaaS auth'."},{"name":"pricing","in":"query","required":false,"schema":{"type":"string"},"description":"Optional pricing model filter."},{"name":"openSource","in":"query","schema":{"type":"boolean"},"description":"Filter for open-source tools."},{"name":"enterpriseReady","in":"query","schema":{"type":"boolean"},"description":"Filter for enterprise-ready tools."},{"name":"apiAvailable","in":"query","schema":{"type":"boolean"},"description":"Filter for tools with an API surface."},{"name":"difficulty","in":"query","schema":{"type":"string","enum":["low","medium","high"]},"description":"Implementation difficulty filter."},{"name":"maturity","in":"query","schema":{"type":"string","enum":["prototype","production","enterprise"]},"description":"Maturity filter."},{"name":"category","in":"query","required":false,"schema":{"type":"string"},"description":"Optional tool category slug."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":30,"default":12},"description":"Maximum recommendations to return."}],"responses":{"200":{"description":"Ranked builder tool recommendations with reasons, filters, docs, pricing, and adoption metadata.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid query.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Search failed.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/v1/adoption":{"get":{"tags":["Discovery"],"operationId":"listPublicAdoptionSignals","summary":"List aggregate public adoption signals.","description":"Returns privacy-safe aggregate adoption rows. It never returns raw developer identity, private workspace metrics, or tenant-scoped enterprise data.","parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by tool category slug."},{"name":"tool","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by tool slug."},{"name":"period","in":"query","schema":{"type":"string","enum":["7d","30d","90d"],"default":"30d"},"description":"Aggregation window."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":25},"description":"Maximum rows to return."}],"responses":{"200":{"description":"Aggregate adoption rows with methodology, suppression, confidence, and rate-limit metadata.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid query.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/v1/agent-rank":{"get":{"tags":["Discovery"],"operationId":"listAgentRankRows","summary":"List public AgentRank rows.","description":"Alias of the public adoption API for agents that search for adoption-ranked AI/devtool products.","responses":{"200":{"description":"Aggregate ranking rows.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/perks":{"get":{"tags":["Discovery"],"operationId":"listPublicPerks","summary":"List public developer credits, perks, and opportunities.","description":"Returns approved live opportunities or clearly labeled public examples. Public cards hide enterprise-only retained/activation metrics.","parameters":[{"name":"toolId","in":"query","required":false,"schema":{"type":"string"},"description":"Optional tool id filter."},{"name":"categorySlug","in":"query","required":false,"schema":{"type":"string"},"description":"Optional category slug filter."},{"name":"inviteToken","in":"query","required":false,"schema":{"type":"string"},"description":"Optional invite token for a specific provider program."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Maximum perks to return."}],"responses":{"200":{"description":"Public perk list and viewer context.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid query.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"503":{"description":"Live perk data unavailable and demo fallback disabled.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/perks/submissions":{"post":{"tags":["Enterprise intake"],"operationId":"submitEnterprisePerkForReview","summary":"Submit a public perk, credit, or developer program for intake.","description":"No signup required. Creates an enterprise lead and runs deterministic intake. High-confidence company-domain offers can become public immediately; ambiguous offers stay queued for evidence.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerkSubmissionInput"}}}},"responses":{"200":{"description":"Duplicate already accepted; idempotent success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"201":{"description":"Submission accepted; response includes reviewStatus and autopilotStatus.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Spam honeypot ignored.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid submission.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/usage/track/dry-run":{"post":{"tags":["Tracking"],"operationId":"dryRunUsageTrackingEvent","summary":"Validate a usage/adoption event without storing it.","security":[{"trackingKey":[]}],"description":"Requires a customer-issued tracking key. Use this before production writes so agents and customers can inspect event family mapping, product resolution, and next fixes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageTrackingEvent"}}}},"responses":{"200":{"description":"Accepted dry-run mapping.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Valid payload but product policy says not to track.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid payload or unknown event name.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid tracking key.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/usage/track":{"post":{"tags":["Tracking"],"operationId":"recordUsageTrackingEvent","summary":"Record a usage/adoption event.","security":[{"trackingKey":[]}],"description":"Requires a customer-issued tracking key. Organization keys must include product identity so adoption can be separated by API, model, workflow, integration, or agent.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageTrackingEvent"}}}},"responses":{"200":{"description":"Tracked event with mapping metadata.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Valid payload but product policy says not to track.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid payload or unknown event name.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid tracking key.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/integrations/segment/connection":{"get":{"tags":["Tracking"],"operationId":"getSegmentProofConnectConfig","summary":"Return Segment Proof Connect V1 install configuration.","description":"Returns machine-readable Segment destination function code, required settings, event mapping, OAuth-next instructions, and the relay endpoint. It never returns tracking keys or customer secrets.","parameters":[{"name":"productId","in":"query","required":false,"schema":{"type":"string"},"description":"Optional partner product id to prefill in the Segment destination wrapper."},{"name":"productName","in":"query","required":false,"schema":{"type":"string"},"description":"Optional partner product name to prefill in the Segment destination wrapper."},{"name":"productType","in":"query","required":false,"schema":{"type":"string"},"description":"Optional product type such as api, sdk, agent, workflow, docs, or other."},{"name":"campaignId","in":"query","required":false,"schema":{"type":"string"},"description":"Optional campaign or launch id for attribution."},{"name":"campaignName","in":"query","required":false,"schema":{"type":"string"},"description":"Optional campaign or launch name for attribution."}],"responses":{"200":{"description":"Segment destination function configuration and verification checklist.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/usage/analytics/relay":{"post":{"tags":["Tracking"],"operationId":"relayAnalyticsUsageEvents","summary":"Relay Segment/PostHog-style analytics events into adoption proof.","security":[{"trackingKey":[]}],"description":"Requires a customer-issued tracking key. Accepts a single analytics event, Segment batch, PostHog events array, or wrapper with product/eventMap/default context. Use dryRun=1 before production writes. Optional x-tokensand-signature uses HMAC-SHA256 over the raw body with the tracking key.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"string","enum":["1"]},"description":"Validate mapping without storing events."},{"name":"source","in":"query","schema":{"type":"string","enum":["segment","posthog","generic"]},"description":"Optional source override when the payload does not identify the analytics provider."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Analytics payload or wrapper. Include product for organization keys unless every source event carries product identity."}}}},"responses":{"200":{"description":"Dry-run mapping accepted.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"201":{"description":"Analytics events stored.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"207":{"description":"Some events mapped or stored; some need fixes.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid JSON, empty event batch, or invalid mapped payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing tracking key or invalid required signature.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/agent-install/events":{"post":{"tags":["Agent distribution"],"operationId":"recordAgentInstallFunnelEvent","summary":"Record anonymous or signed-in Tokens& agent install funnel events.","description":"Accepts install-page and MCP runtime events for measuring install page view, config copy, MCP first tool call, Build Packet read, perk exposure, and project proof. The endpoint never requires signup for top-of-funnel measurement.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["event"],"properties":{"event":{"type":"string","enum":["agent_install_page_viewed","agent_install_config_copied","agent_install_deeplink_opened","agent_install_mcp_first_tool_call","agent_install_mcp_tool_call","agent_install_build_packet_read","agent_install_perk_shown","agent_install_project_proof_drafted","agent_install_project_proof_published"]},"anonymousId":{"type":"string","maxLength":200},"source":{"type":"string","maxLength":80},"metadata":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"Event persisted.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Event accepted but not persisted, usually because the platform tool id is not configured.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/workflow/context":{"get":{"tags":["Workflow"],"operationId":"getDeveloperWorkflowContext","summary":"Fetch scoped developer/project context for a coding agent.","security":[{"workflowToken":[]},{"sessionCookie":[]}],"description":"Returns only the signed-in developer or workflow-token scope. Supports JSON by default and Markdown via format=markdown or Accept: text/markdown.","parameters":[{"name":"projectId","in":"query","required":false,"schema":{"type":"string"},"description":"Optional project id when using a session or unscoped workflow token."},{"name":"format","in":"query","schema":{"type":"string","enum":["markdown"]},"description":"Return Markdown instead of JSON."}],"responses":{"200":{"description":"Scoped workflow context.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Token is scoped to a different project.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/workflow/build-packet":{"get":{"tags":["Workflow"],"operationId":"getBuildPacket","summary":"Fetch the latest agent-ready build packet.","security":[{"workflowToken":[]}],"description":"Returns a Tokens& Build Packet generated from the developer's selected stack recommendation. Supports JSON by default and Markdown via format=markdown or Accept: text/markdown.","parameters":[{"name":"recommendationId","in":"query","required":false,"schema":{"type":"string"},"description":"Optional stack recommendation id."},{"name":"variant","in":"query","required":false,"schema":{"type":"string"},"description":"Optional selected variant key, such as recommended, cheapest, fastest, oss, or enterprise."},{"name":"format","in":"query","schema":{"type":"string","enum":["markdown"]},"description":"Return Markdown instead of JSON."}],"responses":{"200":{"description":"Agent-ready build packet.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid workflow token.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"No recommendation found for this workflow token.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Invalid recommendation snapshot.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/workflow/mcp-config":{"post":{"tags":["Workflow"],"operationId":"createWorkflowMcpConfig","summary":"Create scoped MCP/Codex/Cursor workflow config snippets.","security":[{"sessionCookie":[]}],"description":"Requires a signed-in session. Returns scoped config snippets and a workflow token. External writes and public publishing remain approval-gated.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"projectId":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"Workflow config snippets and quota metadata.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Project not found.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}}},"components":{"securitySchemes":{"trackingKey":{"type":"http","scheme":"bearer","description":"Customer-issued Tokens& tracking key."},"workflowToken":{"type":"http","scheme":"bearer","description":"Developer workflow token generated from the signed-in dashboard."},"sessionCookie":{"type":"apiKey","in":"cookie","name":"sb-access-token","description":"Authenticated browser session. Exact cookie names are deployment-specific."}},"schemas":{"PerkSubmissionInput":{"type":"object","additionalProperties":false,"required":["workEmail","perkUrl"],"properties":{"companyName":{"type":"string","maxLength":120},"workEmail":{"type":"string","format":"email","description":"Business email required."},"name":{"type":"string","maxLength":120},"title":{"type":"string","maxLength":120},"companyWebsite":{"type":"string","format":"uri"},"perkTitle":{"type":"string","maxLength":160},"perkUrl":{"type":"string","format":"uri"},"perkType":{"type":"string","enum":["FREE_TIER","CREDITS","EVENT","CHALLENGE","MENTORSHIP","STARTUP_BUNDLE","OTHER"]},"creditValue":{"type":"string","maxLength":160},"targetAudience":{"type":"string","maxLength":500},"redemptionPath":{"type":"string","maxLength":800},"expiration":{"type":"string","maxLength":120},"notes":{"type":"string","maxLength":1500},"website":{"type":"string","description":"Honeypot field. Leave empty."}}},"UsageTrackingEvent":{"type":"object","additionalProperties":true,"required":["eventType"],"properties":{"eventType":{"type":"string","description":"Canonical event type or customer event name."},"event_name":{"type":"string","description":"Alternative event name field."},"eventFamily":{"type":"string","enum":["intent","evaluation","activation","retention","expansion","commercial"]},"developerId":{"type":"string"},"userId":{"type":"string"},"email":{"type":"string","format":"email"},"product":{"type":"object","additionalProperties":true,"description":"Required when using an organization tracking key.","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"version":{"type":"string"}}},"account":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string"},"domain":{"type":"string"}}},"workflow":{"type":"string"},"metadata":{"type":"object","additionalProperties":true}}}}}}