{"openapi":"3.1.0","info":{"title":"tokens& public and agent-facing API","version":"2026-09-17","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-canonical-surfaces":{"developer":{"primary":"https://tokensand.com","buildWorkbench":"https://tokensand.com/tools","aiToolsForDevelopers":"https://tokensand.com/tools?mode=build","agentSkills":"https://tokensand.com/agent-skills","mcpServers":"https://tokensand.com/mcp-servers","installInAgents":"https://tokensand.com/agents/install"},"enterprise":{"primary":"https://tokensand.com/platform","programAttribution":"https://tokensand.com/developer-program-attribution","adoptionIntelligence":"https://tokensand.com/developer-adoption-intelligence","roi":"https://tokensand.com/roi","methodology":"https://tokensand.com/report/methodology"},"agentDiscovery":{"llms":"https://tokensand.com/llms.txt","fullContext":"https://tokensand.com/llms-full.txt","auth":"https://tokensand.com/auth.md","openapi":"https://tokensand.com/openapi.json","agentPack":"https://tokensand.com/.well-known/tokensand-agent-pack.json"}},"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/directory/context":{"get":{"tags":["Discovery"],"operationId":"getDirectoryAgentContext","summary":"Fetch live directory context with receipt metadata for agents.","description":"Returns DB-backed tool rows, live directory facets, tracked action URLs, and a receipt ID agents can cite and pass through click, save, proof, and project attribution. Public reads are catalog-safe; signed-in sessions or workflow tokens additionally persist the request event.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":300},"description":"Natural language build intent such as 'support agent with RAG over docs'. Alias: query."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":20,"default":8},"description":"Maximum tool rows to return."},{"name":"source","in":"query","schema":{"type":"string","enum":["api","chat","mcp","search","workflow"],"default":"api"},"description":"Calling surface for attribution."},{"name":"format","in":"query","schema":{"type":"string","enum":["json","markdown"],"default":"json"},"description":"Return Markdown instead of JSON when an agent prefers text context."}],"responses":{"200":{"description":"Directory context receipt with tools, facets, tracked actions, and attribution metadata.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid query.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Invalid bearer workflow token.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Workflow token is missing tools:read or project:read scope.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Context retrieval failed.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"post":{"tags":["Discovery"],"operationId":"postDirectoryAgentContext","summary":"Fetch live directory context from a JSON body.","description":"Same response as GET /api/directory/context, useful for agents that prefer JSON-RPC-style body payloads.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectoryContextRequest"}}}},"responses":{"200":{"description":"Directory context receipt with tools, facets, tracked actions, and attribution metadata.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Invalid bearer workflow token.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Workflow token is missing tools:read or project:read scope.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Context retrieval 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. This read does not claim an offer or redeem provider credits. Catalog eligibility is not provider approval; inspect provider terms, expiry, billing, and account requirements. 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":"search","in":"query","schema":{"type":"string","maxLength":200},"description":"Optional text match across offer, provider, and tool names/descriptions."},{"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":40},"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/agent-skills":{"get":{"tags":["Discovery"],"operationId":"listPublicAgentSkills","summary":"List public SKILL.md Agent Skills in the Tokens& registry.","description":"Returns the vendor-authored Agent Skills published at /agent-skills, with canonical page URLs, raw SKILL.md URLs, source repositories, licenses, and declared coding-agent clients. A skill qualifies from a non-empty source snapshot and summary. sourceFetchedAt dates that snapshot and sourceSha256 identifies it; this is not a live availability or compatibility check. Listings do not verify installation, security, vendor participation, or product use. Response metadata omits the SKILL.md body; fetch skillMarkdownUrl for current upstream content, which may differ from the snapshot.","parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string"},"description":"Optional category filter (Agents, Backend, Frontend, Models, Payments, Docs)."},{"name":"client","in":"query","required":false,"schema":{"type":"string"},"description":"Optional supported-client filter (for example Codex, Cursor, Claude Code)."},{"name":"vendor","in":"query","required":false,"schema":{"type":"string"},"description":"Optional vendor name filter."},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Optional free-text match across title, vendor, summary, category, and tags."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":200},"description":"Maximum skills to return."}],"responses":{"200":{"description":"Registry metadata, category/client/vendor facets, and matching Agent Skills.","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/perks/submissions":{"post":{"tags":["Enterprise intake"],"operationId":"submitEnterpriseLaunchOrPerkForReview","summary":"Submit a public launch, perk, credit, or developer program for intake.","description":"No signup required. Creates a private intake record and runs deterministic validation and triage. Automation may prepare private drafts, but a signed-in, authorized human must review and approve them before publication or provisioning.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerkSubmissionInput"}}}},"responses":{"202":{"description":"Submission received for human review, duplicate received idempotently, or 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, usage receipt metadata, 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, agent, or usage receipt.","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_agent_skill_drafted","agent_install_agent_skill_published","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/me/usage":{"get":{"tags":["Workflow"],"operationId":"getBuilderUsageReceipts","summary":"Read the owner's connected tools and self-reported receipt summary.","security":[{"workflowToken":[]},{"sessionCookie":[]}],"description":"Requires account-level project:read or a browser session. Project-bound tokens are forbidden. Connection flags vendorOrganizationLinked and reconnectRequired qualify sharing consent; sharedWithVendor is not delivery confirmation. Unknown spend stays null. Private provider balances use a separate endpoint.","responses":{"200":{"description":"Private receipt summary.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Account scope required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"post":{"tags":["Workflow"],"operationId":"recordBuilderUsageReceipt","summary":"Record a real operation against an explicitly connected tool.","security":[{"workflowToken":[]},{"sessionCookie":[]}],"description":"Requires account-level project:publish or a browser session and current explicit sharing consent from /dashboard/usage?mode=developer. Never auto-connects. Send one receipt or {events:[receipt,...]} (maximum 100). Reuse the original operation ID as idempotencyKey on retries; retry only reporting, never the provider call. Include only known success, durationMs and spendCents. Optional projectId must identify the owner's published project listing this tool. These are self-reported receipts, not verified activation, retention, provider balances or revenue. Results distinguish queued (not confirmed delivery), vendor_unlinked, existing_receipt and relay_unavailable. Vendor ownership changes require explicit browser reconnection. Never send secrets, queries or customer data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"toolId":{"type":"string","format":"uuid","description":"Provide toolId or toolSlug."},"toolSlug":{"type":"string","maxLength":200},"receiptType":{"type":"string","enum":["model_call","mcp_tool_call","api_call","custom"]},"idempotencyKey":{"type":"string","maxLength":200,"description":"Stable original operation ID, reused on retries."},"workflowName":{"type":"string","maxLength":200},"projectId":{"type":"string","format":"uuid"},"success":{"type":"boolean"},"durationMs":{"type":"integer","minimum":0,"maximum":86400000},"spendCents":{"type":"integer","minimum":0,"maximum":100000000,"description":"Actual known USD cents; omit unknown cost."}}}}}},"responses":{"200":{"description":"Receipts recorded; inspect per-result deliveryStatus and errors.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid receipt.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Account scope or owned published project required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"No receipts accepted; inspect connection and tool errors.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/me/usage/spending":{"get":{"tags":["Workflow"],"operationId":"getPrivateAccountSpending","summary":"Read private monthly charges and the agent-synced Codex allowance.","security":[{"workflowToken":[]},{"sessionCookie":[]}],"parameters":[{"name":"month","in":"query","required":false,"schema":{"type":"string"},"description":"Optional current or earlier UTC month, YYYY-MM."}],"description":"Account-level project:read or browser session required; project-bound tokens forbidden. Returns month, original totalsByCurrency/monthlyEntries, partial/unreported coverage, codexSnapshot, codexCreditReferenceValue and derived usdEstimate. usdEstimate uses dated ECB reference rates from the fixed public daily XML feed, cached one hour and rejected after seven days. Original currencies remain separate. Original amounts are never rewritten. totalCents is null if any conversion is missing; knownSubtotalCents is incomplete, never a total. USD-only and explicit zero need no FX. Estimates are not invoice/card exchange rates or additional bank FX fees. Credit reference values are noncash and never added to paid amounts. Reads never contact OpenAI, sync accounts or emit usage events; only the public ECB feed may be fetched without private input. Responses are private, no-store.","responses":{"200":{"description":"Private saved monthly charges and allowance.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid month.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Account scope required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"503":{"description":"Saved data unavailable.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"post":{"tags":["Workflow"],"operationId":"recordPrivateAccountSpending","summary":"Replace a reported monthly amount or import a Codex allowance snapshot.","security":[{"workflowToken":[]},{"sessionCookie":[]}],"description":"Account-level project:publish or same-origin browser session required. Monthly amount replaces the existing provider/month/currency total, never adds twice. Codex groups ChatGPT subscription and extra credit purchases; OpenAI API bills are separate and unsupported here. Use original billing currency, not a guessed conversion. Never add app-reported receipt costs, allowance percentages, credit balance, or estimated Tavily overage to monthly charges. Codex snapshots are agent_reported; use only a supported signed-in account usage tool. Unknown counters remain null. No OpenAI credentials, invoice links, card details, prompts or raw provider responses accepted. Does not purchase credits or create a live OAuth connection. Older snapshots cannot overwrite newer ones. Monthly history is bounded to 24 entries per provider/currency.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type","provider","month","amountCents"],"properties":{"type":{"type":"string","enum":["monthly_spend"]},"provider":{"type":"string","enum":["codex","tavily","brightdata"]},"month":{"type":"string","pattern":"^20[0-9]{2}-(0[1-9]|1[0-2])$"},"currency":{"type":"string","enum":["USD","MXN","EUR","GBP"],"default":"USD"},"amountCents":{"type":"integer","minimum":0,"maximum":100000000,"description":"Whole minor units in the selected currency."},"source":{"type":"string","enum":["user_reported","agent_reported"],"default":"user_reported"}}},{"type":"object","additionalProperties":false,"required":["type","checkedAt","planType","creditsBalance","primary"],"properties":{"type":{"type":"string","enum":["codex_snapshot"]},"checkedAt":{"type":"string","format":"date-time","description":"At most five minutes ahead of server time."},"planType":{"type":["string","null"],"enum":["free","go","plus","pro","team","business","enterprise","edu","unknown",null]},"creditsBalance":{"type":["number","null"],"minimum":0,"maximum":1000000000},"primary":{"$ref":"#/components/schemas/CodexAllowanceWindow"},"secondary":{"$ref":"#/components/schemas/CodexAllowanceWindow"}}}]}}}},"responses":{"200":{"description":"Updated saved summary; updated:false preserves a newer or identical record.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid bounded input.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Account scope or same origin required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"409":{"description":"History limit reached.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate limited; honor Retry-After.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"503":{"description":"Save unavailable; reload to confirm current state.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"delete":{"tags":["Workflow"],"operationId":"deletePrivateAccountSpending","summary":"Remove an owned monthly amount or Codex snapshot.","security":[{"workflowToken":[]},{"sessionCookie":[]}],"description":"Requires account-level project:publish or same-origin session. Send {type:'monthly_spend',provider,month,currency} or {type:'codex_snapshot'}. Never deletes provider accounts or changes billing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type","provider","month"],"properties":{"type":{"type":"string","enum":["monthly_spend"]},"provider":{"type":"string","enum":["codex","tavily","brightdata"]},"month":{"type":"string"},"currency":{"type":"string","enum":["USD","MXN","EUR","GBP"],"default":"USD"}}},{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["codex_snapshot"]}}}]}}}},"responses":{"200":{"description":"Current saved summary.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid selection.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Account scope or same origin required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"503":{"description":"Delete unavailable; reload to confirm current state.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/me/usage/providers/brightdata":{"get":{"tags":["Workflow"],"operationId":"getPrivateBrightDataUsage","summary":"Read the owner's saved Bright Data balance without contacting the provider.","security":[{"workflowToken":[]},{"sessionCookie":[]}],"description":"Requires account-level project:read or an authenticated browser session; project-bound tokens are forbidden. Returns {snapshot:null} when no saved balance exists. Currency is populated only when the provider explicitly reports a supported currency; missing amounts and currency remain null. Free MCP request allowance and billed USD remain unknown. checkedAt is the lookup start time, not a freshness guarantee. Responses are private, no-store.","responses":{"200":{"description":"Private saved balance or null.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["snapshot"],"properties":{"snapshot":{"oneOf":[{"$ref":"#/components/schemas/BrightDataBalanceSnapshot"},{"type":"null"}]}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Account scope required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"503":{"description":"Stored balance unavailable.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"post":{"tags":["Workflow"],"operationId":"syncPrivateBrightDataUsage","summary":"Check a private Bright Data balance using a transient API key.","security":[{"workflowToken":[]},{"sessionCookie":[]}],"description":"Requires account-level project:publish or a same-origin browser session; project-bound tokens are forbidden. Accepts only {apiKey}; the trimmed key is used transiently for one GET https://api.brightdata.com/customer/balance with an eight-second timeout, no redirects and no automatic retries. Never stores credentials, invoice contents, raw provider responses or customer data. Persists only a sanitized owner-private balance snapshot. Maximum 8 syncs/account/10 minutes; honor Retry-After. Returns {snapshot,updated}; updated:false retains a newer saved snapshot. Balance and pendingAmount are not monthly spend; never derive billed dollars or remaining free MCP requests from them. Confirmed monthly bills are recorded separately through /api/me/usage/spending. Does not redeem credits, establish product-use evidence, change billing or share adoption events. Responses are private, no-store.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["apiKey"],"properties":{"apiKey":{"type":"string","writeOnly":true,"minLength":16,"maxLength":512,"pattern":"^[a-zA-Z0-9_-]+$","description":"Provider key only. Never include it in a URL, prompt, public source, logs or saved metadata."}}}}}},"responses":{"200":{"description":"Private balance synced or newer snapshot retained.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["snapshot","updated"],"properties":{"snapshot":{"$ref":"#/components/schemas/BrightDataBalanceSnapshot"},"updated":{"type":"boolean"}}}}}},"400":{"description":"Invalid bounded sync details.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Unauthorized or PROVIDER_KEY_REJECTED.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Account scope, same origin or provider account permission required; inspect safe error code.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Account or provider rate limit; honor Retry-After.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"502":{"description":"Provider response unavailable or unsupported.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"503":{"description":"Sync unavailable; previous snapshot unchanged.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"504":{"description":"Provider timeout; retry sync later.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/me/usage/providers/tavily":{"get":{"tags":["Workflow"],"operationId":"getPrivateTavilyUsage","summary":"Read the owner's saved Tavily credit balance without contacting Tavily.","security":[{"workflowToken":[]},{"sessionCookie":[]}],"description":"Requires an account-level project:read token or authenticated browser session. Project-bound tokens are forbidden. Returns {snapshot:null} when not connected. A snapshot contains canonical tool and offer identities, checkedAt, plan/key/PAYGO credit counters (unknown values are null), and optional client-reported lastRun. Provider counters may lag recent calls; checkedAt is the lookup time. Retain local credit reservations until counters catch up. Billed USD is always unknown; credit totals are shared account/key totals, not project history. Responses are private, no-store.","responses":{"200":{"description":"Saved snapshot or null.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Account scope required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"503":{"description":"Stored usage unavailable.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"post":{"tags":["Workflow"],"operationId":"syncPrivateTavilyUsage","summary":"Sync a private Tavily credit snapshot using a transient server-side key.","security":[{"workflowToken":[]},{"sessionCookie":[]}],"description":"Requires an account-level project:publish token or browser session. Keep keys in server environment variables, never prompts or client code. Uses the supplied key once for GET https://api.tavily.com/usage; never stores the key, search query/results, or vendor-shared adoption events. Call after successful app use, coalesce to at most once per 90 seconds, respect Retry-After, and retry only sync if it fails; never repeat Search to repair a receipt. Tokens& limits each account to 8 syncs/10 minutes; Tavily's separate usage limit also applies. Returns {snapshot,updated}; updated:false retains a newer saved response. This does not enable PAYGO, redeem a perk, or establish invoice costs.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["apiKey"],"properties":{"apiKey":{"type":"string","writeOnly":true,"minLength":10,"maxLength":512,"pattern":"^tvly-[a-zA-Z0-9_-]+$"},"lastRun":{"type":"object","additionalProperties":false,"required":["occurredAt"],"properties":{"occurredAt":{"type":"string","format":"date-time","description":"Client-reported run time, at most five minutes ahead of server time."},"requestId":{"type":"string","maxLength":200,"description":"Tavily response.request_id; no credentials."},"credits":{"type":"number","minimum":0,"description":"Tavily response.usage.credits; omit if unreported."},"durationMs":{"type":"integer","minimum":0,"maximum":86400000},"applicationName":{"type":"string","maxLength":120}}}}}}}},"responses":{"200":{"description":"Private snapshot synced or newer snapshot retained.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid bounded sync details.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Unauthorized or provider key rejected; inspect safe error code.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Account scope required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Sync rate limited; honor Retry-After.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"502":{"description":"Provider response unavailable or unsupported.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"503":{"description":"Sync unavailable; previous snapshot unchanged.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"504":{"description":"Provider timeout; retry sync later.","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. Account context includes private stored providerUsage credit snapshots, accountSpending with unchanged original-currency monthly records, a dated ECB USD estimate, separate noncash credit reference values and an agent-reported Codex allowance, and self-reported receipt usage with explicit spend coverage; reads never contact private provider accounts; a fixed cached public ECB feed can supply USD reference rates. Project-scoped tokens receive only their attached project and recorded stack; account profile, saved stack, recommendations, providerUsage, and Build Packets require a developer token. Compact context with projectId also omits account data; omit projectId to request private account balances. Session-authenticated API calls retain full JSON by default for compatibility; workflow-token calls default to compact unless detail=full is explicit. Supports 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":"detail","in":"query","schema":{"type":"string","enum":["compact","full"]},"description":"Workflow tokens default to compact; session-authenticated calls default to full. Compact omits nested alternatives, examples, detailed cost components, and time modules while preserving the selected stack and Build Packet handoff."},{"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":"Read a saved agent-ready build packet.","security":[{"workflowToken":[]}],"description":"Returns a Tokens& Build Packet generated from the developer's selected stack recommendation. Project-scoped tokens are rejected because Build Packets contain account-wide recommendation context. This reads an existing explicitly saved recommendation; build_brief alone does not save it. REST returns full detail by default for compatibility; request detail=compact to avoid duplicated export content. 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":"detail","in":"query","schema":{"type":"string","enum":["compact","full"],"default":"full"},"description":"Use compact for implementation context; full includes complete export content."},{"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}}}},"400":{"description":"Invalid detail or unavailable recommendation variant.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid workflow token.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Project-scoped token cannot read account-wide Build Packets.","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/projects/draft":{"post":{"tags":["Workflow"],"operationId":"draftWorkflowProject","summary":"Prepare a project for review without publishing or saving it.","security":[{"workflowToken":[]}],"description":"Requires an account-level workflow token with project:publish; project-bound tokens are forbidden and browser cookies alone are insufficient. Uses explicitly supplied repository context and may fetch public repository metadata. Send only context the user authorized for Tokens&; omit secrets and unrelated private files. Returns draft, detectedTools, missingFields, confidence, duplicateProjectHref and quota. This prepares a review result, not a persisted project. Review missing fields, tool identities and repository ownership before the separate confirmed publish operation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"repoUrl":{"type":"string","description":"Public HTTP(S) repository URL, or empty string."},"readme":{"type":"string","maxLength":80000},"packageJson":{"oneOf":[{"type":"string","maxLength":200000},{"type":"object","additionalProperties":true}]},"demoUrl":{"type":"string","description":"HTTP(S) URL, or empty string."},"imageUrl":{"type":"string","description":"HTTP(S) URL, or empty string."},"localMetadata":{"type":"object","additionalProperties":true,"description":"Optional explicitly supplied metadata; the server retains only supported compact fields."}}}}}},"responses":{"200":{"description":"Unpersisted project draft and review context.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing/invalid workflow token or missing project:publish scope.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Project-bound token cannot prepare a new project.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"IP or workflow-token quota exceeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Draft preparation failed.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/workflow/projects":{"post":{"tags":["Workflow"],"operationId":"publishWorkflowProject","summary":"Publish a reviewed project after explicit confirmation.","security":[{"workflowToken":[]}],"description":"Requires an account-level workflow token with project:publish; project-bound tokens are forbidden and browser cookies alone are insufficient. Call draftWorkflowProject first and obtain explicit user approval for the reviewed public content, then send confirm:true. At least one catalog tool or suggested tool is required. OWNER requires verified matching GitHub identity; REFERENCE does not claim repository ownership. Preserve a returned directoryContextReceiptId only with its matching owner and tool lineage. A successful call creates a public project and self-reported adoption records, not verified runtime usage. A 409 duplicate/conflict must be inspected, not blindly retried. Returns project, projectHref, profileHref, detectedTools, enterpriseEventsCreated, shareMoment and quota.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["confirm","title","summary","description"],"properties":{"confirm":{"type":"boolean","const":true,"description":"Set only after the user approves the reviewed public project."},"title":{"type":"string","minLength":5,"maxLength":140},"summary":{"type":"string","minLength":20,"maxLength":240},"description":{"type":"string","minLength":50,"maxLength":8000},"repoUrl":{"type":"string","maxLength":2000,"description":"HTTP(S) URL, or empty string."},"demoUrl":{"type":"string","maxLength":2000,"description":"HTTP(S) URL, or empty string."},"imageUrl":{"type":"string","maxLength":2000,"description":"HTTP(S) URL, or empty string."},"repoOwnershipIntent":{"type":"string","enum":["OWNER","REFERENCE"]},"publicAttributionMode":{"type":"string","enum":["PUBLIC_PROFILE","ANONYMOUS"],"default":"PUBLIC_PROFILE","description":"Choose public profile attribution or an anonymous author. The project remains public in either mode."},"tools":{"type":"array","maxItems":12,"items":{"type":"object","required":["toolId"],"properties":{"toolId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["PRIMARY","USED","EVALUATED","REPLACED"],"default":"USED"},"note":{"type":"string","maxLength":500},"sortOrder":{"type":"integer","minimum":0,"maximum":100,"default":0}}}},"suggestedTools":{"type":"array","maxItems":12,"items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":2,"maxLength":80},"packageName":{"type":"string","maxLength":120},"categorySlug":{"type":"string","maxLength":80},"source":{"type":"string","enum":["dependency","manual"],"default":"manual"},"role":{"type":"string","enum":["PRIMARY","USED","EVALUATED","REPLACED"],"default":"USED"},"note":{"type":"string","maxLength":500},"sortOrder":{"type":"integer","minimum":0,"maximum":100,"default":0}}}},"sourceAttribution":{"type":"object","description":"Optional reviewed attribution from the draft/Build Packet. directoryContextReceiptId is server-validated against the owner and selected catalog tools; never manufacture a receipt. Unsupported properties are ignored.","properties":{"recommendationId":{"anyOf":[{"type":"string","format":"uuid"},{"const":""}]},"source":{"type":"string","maxLength":200},"medium":{"type":"string","maxLength":200},"campaign":{"type":"string","maxLength":200},"content":{"type":"string","maxLength":200},"term":{"type":"string","maxLength":200},"ref":{"type":"string","maxLength":200},"directoryContextReceiptId":{"type":"string","maxLength":200},"directoryContextSource":{"type":"string","maxLength":200},"offeringId":{"type":"string","maxLength":200},"interventionId":{"type":"string","maxLength":200},"directoryContextQuery":{"type":"string","maxLength":300},"toolIds":{"type":"string","maxLength":1000},"eventUrl":{"anyOf":[{"type":"string","format":"uri","pattern":"^https?://","maxLength":1200},{"const":""}]},"landingPath":{"type":"string","maxLength":1000}}}},"anyOf":[{"required":["tools"],"properties":{"tools":{"minItems":1}}},{"required":["suggestedTools"],"properties":{"suggestedTools":{"minItems":1}}}]}}}},"responses":{"201":{"description":"Published public project and self-reported adoption context.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid input, unavailable tool, or invalid receipt lineage.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing/invalid workflow token or missing project:publish scope.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Project-bound token or repository ownership is not authorized.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"409":{"description":"Existing project, publication conflict, or previously claimed receipt; inspect before another attempt.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"428":{"description":"Confirmation required; no project persisted.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Workflow-token quota or enterprise outbox capacity exceeded; honor Retry-After when supplied.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Publication failed; inspect whether the project exists before retrying.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/workflow/agent-skills":{"post":{"tags":["Workflow"],"operationId":"publishAgentSkillFromSkillMd","summary":"Parse and import a private Agent Skill draft from a public SKILL.md URL.","security":[{"workflowToken":[]},{"sessionCookie":[]}],"description":"Agent-native path for Codex, Cursor, Claude Code, and MCP hosts. First call without confirm to parse the public SKILL.md and return a normalized draft. After human review, call again with confirm=true to create a private dashboard draft. Public publishing is a separate authenticated dashboard action after the install path is verified.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSkillWorkflowInput"}}}},"responses":{"200":{"description":"Parsed draft; no write occurred because confirm was false.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"201":{"description":"Agent Skill created.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid payload or SKILL.md URL.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid workflow token/session.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Insufficient publishing scope, project-scoped token, or organization admin permission required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Linked product/tool not found.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"408":{"description":"SKILL.md import timed out.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate limit exceeded.","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. Omit projectId to create a developer token for approval-gated project and Agent Skill draft/publish workflows. Supply an owned projectId to create a least-privilege project read token; project tokens cannot create projects or import Agent Skills.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"projectId":{"type":"string","format":"uuid","nullable":true}}}}}},"responses":{"200":{"description":"Workflow config snippets and quota metadata.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request or project id.","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":{"BrightDataBalanceSnapshot":{"type":"object","additionalProperties":false,"required":["provider","source","checkedAt","balance","freeTier","spending"],"properties":{"provider":{"type":"string","const":"brightdata"},"source":{"type":"string","const":"provider_api"},"checkedAt":{"type":"string","format":"date-time","description":"Server timestamp when the provider balance lookup started."},"balance":{"type":"object","additionalProperties":false,"required":["amount","pendingAmount","currency"],"properties":{"amount":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000},"pendingAmount":{"type":["number","null"],"minimum":-1000000000,"maximum":1000000000,"description":"Provider pending amount, never a monthly billed total."},"currency":{"type":["string","null"],"enum":["USD","EUR","GBP","MXN",null],"description":"Only an explicitly reported supported currency; never inferred as USD."}}},"freeTier":{"type":"object","additionalProperties":false,"required":["remainingRequests","limit"],"properties":{"remainingRequests":{"type":"null"},"limit":{"type":"null"}}},"spending":{"type":"object","additionalProperties":false,"required":["billedUsd"],"properties":{"billedUsd":{"type":"null"}}}}},"CodexAllowanceWindow":{"type":"object","additionalProperties":false,"required":["usedPercent","windowDurationMins","resetsAt"],"properties":{"usedPercent":{"type":["number","null"],"minimum":0,"maximum":100},"windowDurationMins":{"type":["integer","null"],"minimum":1,"maximum":525600},"resetsAt":{"type":["integer","null"],"minimum":0,"maximum":4102444800,"description":"Unix seconds."}}},"DirectoryContextRequest":{"type":"object","additionalProperties":false,"required":["q"],"properties":{"q":{"type":"string","minLength":2,"maxLength":300},"limit":{"type":"integer","minimum":1,"maximum":20,"default":8},"source":{"type":"string","enum":["api","chat","mcp","search","workflow"],"default":"api"},"format":{"type":"string","enum":["json","markdown"],"default":"json"}}},"DirectoryContextReceipt":{"type":"object","required":["schemaVersion","receiptId","query","source","metrics","facets","tools","tracking"],"properties":{"schemaVersion":{"type":"string","const":"tokensand-directory-context-v1"},"receiptId":{"type":"string","description":"Join key for later click, save, proof, project, and report attribution."},"query":{"type":"string"},"source":{"type":"string","enum":["api","chat","mcp","search","workflow"]},"status":{"type":"string","enum":["completed","empty"]},"summary":{"type":"string"},"metrics":{"type":"object","additionalProperties":true},"facets":{"type":"object","additionalProperties":true},"tools":{"type":"array","items":{"type":"object","required":["id","name","slug","categorySlug","sourceType","actions"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"categorySlug":{"type":"string"},"sourceType":{"type":"string"},"docsUrl":{"type":["string","null"]},"websiteUrl":{"type":["string","null"]},"pricingModel":{"type":["string","null"]},"openSource":{"type":"boolean"},"apiAvailable":{"type":"boolean"},"reasons":{"type":"array","items":{"type":"string"}},"actions":{"type":"object","additionalProperties":true}}}},"tracking":{"type":"object","additionalProperties":true}}},"AgentSkillWorkflowInput":{"type":"object","additionalProperties":false,"required":["skillUrl"],"properties":{"skillUrl":{"type":"string","format":"uri","maxLength":2000,"description":"Public raw SKILL.md, GitHub, docs, or package URL to parse. Do not include credentials."},"confirm":{"type":"boolean","default":false,"description":"False returns a review draft. True creates the Agent Skill."},"status":{"type":"string","enum":["DRAFT"],"default":"DRAFT","description":"Workflow imports are always private drafts. Publish separately from the authenticated dashboard after verifying the install path."},"name":{"type":"string","minLength":2,"maxLength":200},"outcome":{"type":"string","minLength":5,"maxLength":500},"description":{"type":"string","minLength":10,"maxLength":2000},"repository":{"type":"string","format":"uri","maxLength":500},"homepage":{"type":"string","format":"uri","maxLength":500},"license":{"type":"string","maxLength":50},"organizationId":{"type":"string","format":"uuid"},"toolId":{"type":"string","format":"uuid"},"integrations":{"type":"array","maxItems":10,"items":{"type":"string","maxLength":50}},"tags":{"type":"array","maxItems":10,"items":{"type":"string","maxLength":30}}}},"PerkSubmissionInput":{"type":"object","additionalProperties":false,"required":["workEmail","perkUrl"],"properties":{"submissionKind":{"type":"string","enum":["launch","perk"],"default":"perk"},"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},"wantFeatured":{"type":"boolean","default":false},"website":{"type":"string","description":"Honeypot field. Leave empty."}}},"UsageTrackingEvent":{"type":"object","additionalProperties":true,"properties":{"eventType":{"type":"string","enum":["INSTALL","SIGNUP","API_KEY_CREATED","FIRST_API_CALL","API_CALL","SDK_INITIALIZED","PROJECT_CREATED","DEPLOY","SUBMISSION","CUSTOM"],"description":"Optional server event type. Custom names should be sent through event_name with event_family."},"event_name":{"type":"string","description":"Stable event name such as MODEL_CALL_COMPLETED, MCP_TOOL_CALL_SUCCEEDED, MCP_TOOL_CALL_FAILED, FIRST_API_CALL, or STACK_SPEND_REPORTED."},"eventFamily":{"type":"string","enum":["intent","evaluation","activation","retention","expansion","commercial"]},"event_family":{"type":"string","enum":["intent","evaluation","activation","retention","expansion","commercial"]},"event_id":{"type":"string","description":"Stable source event ID. Required for organization tracking keys so retries cannot duplicate enterprise evidence."},"idempotencyKey":{"type":"string","description":"Camel-case alias for event_id. Required for organization tracking keys when event_id is omitted."},"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":"object","additionalProperties":true},"workload":{"type":"object","additionalProperties":true,"description":"Optional MCP/agent/API workload run. Include id/name/type, processor, endpoint, runId, status, success, latencyMs, requestCount, creditCents, retryCount, errorCount, and error code/message when available."},"mcp_server":{"type":"string","description":"MCP server or connector name, for example supabase or llamaindex."},"mcp_tool":{"type":"string","description":"MCP tool/function name invoked by the agent."},"agent_framework":{"type":"string","description":"Agent framework, for example llamaindex, langgraph, crewai, mastra, custom."},"model_provider":{"type":"string","description":"Model or runtime provider, for example openai, anthropic, google, groq, local."},"tokens_consumed":{"type":"integer","minimum":0},"credit_cents":{"type":"integer","minimum":0,"description":"Observed cost for this event in cents."},"latency_ms":{"type":"integer","minimum":0},"retry_count":{"type":"integer","minimum":0},"error_count":{"type":"integer","minimum":0},"metadata":{"type":"object","additionalProperties":true,"properties":{"usageReceipt":{"type":"object","additionalProperties":true,"description":"Optional tokensand-usage-receipt-v1 metadata with receiptType, provider/model/MCP/API identity, cost, latency, request counts, and recommended stack action. Do not include raw prompts, secrets, private payloads, or source code."},"repositoryEvidence":{"type":"object","additionalProperties":false,"description":"Public repository context only. This endpoint recursively removes provider receipts, signatures, verification flags, and server trust stamps. Paid quarterly repository counts are minted only by an authenticated provider-callback integration, never by caller-selected IMPORT metadata.","required":["provider","repositoryUrl","repositoryActivityAt"],"properties":{"provider":{"type":"string","enum":["github"]},"integrationDetected":{"type":"boolean","const":true},"repositoryUrl":{"type":"string","format":"uri","description":"HTTPS github.com owner/repository URL."},"repositoryActivityAt":{"type":"string","format":"date-time","description":"Caller-observed context only; it does not mint verified contract evidence."}}}}}}}}}}