Startup Tier agent API reference

Read-only company evidence through a scoped JSON API and MCP tools. Availability is configured separately for each environment. Check Settings → Agent integrations before connecting; public documentation does not grant access.

Founders use Startup Tier for free. Company users run startup programs. Agent access requires the owning company's active or trialing Platform subscription and a key issued by the personal company owner or a current admin of the selected shared workspace. One user can own startups and a company; an agent grant covers only the company evidence described here.

Get started

1. Select the intended company workspace, sign in as its personal owner or a current shared-workspace admin, and open Settings → Agent integrations. If integrations are awaiting activation, wait for the operator; do not use demo accounts or bypass the gate.
2. Choose a descriptive key name, ownership (User or Organization in shared workspaces), only the read permissions your client needs, and an expiry of 1, 7 or 30 days. No permissions are selected initially.
3. Create the key and save it directly in your client's secret manager. It is masked initially, available only in the issuing screen, and cleared after five minutes or dismissal. The application provides no later secret-retrieval endpoint.
4. Configure a client that supports a bearer key with the endpoint on the same environment where the key was issued. Production uses https://startuptier.com; sandbox uses https://sandbox.startuptier.com. Do not send a production key to sandbox or to another host.
5. Start with authenticated discovery (GET /api/agent) or the MCP initialization exchange below. Available tools depend on the granted scopes.

The mechanism is a Clerk user or organization API key registered through Startup Tier Settings. Personal workspaces issue user keys. Shared-workspace admins can choose user keys, which require the issuer to remain an active admin, or organization keys, which stay with the workspace after the issuer leaves. Any current workspace admin can revoke either kind. Organization keys cannot receive notifications:read, which exposes individual preferences. A Clerk backend secret, browser session token, OAuth token, or key created independently in Clerk's profile UI is not an agent credential for this API. Automatic OAuth connection is unavailable in this release. Hosted clients that require OAuth cannot connect using this contract.

Endpoints and authentication

Every agent request sends Authorization: Bearer <issued key>. Use HTTPS on the chosen environment. Non-browser clients may omit Origin; browsers must send the site's own Origin. CORS access from unrelated browser sites is unsupported. Keep keys out of URLs, prompts, source control, browser storage, screenshots, logs, and error reports.

The key-management paths are for the human UI. Agent credentials cannot create, inspect, or revoke grants through them. Human mutations also require the site's Origin. There is no OAuth authorization-server metadata, dynamic client registration, or server-session endpoint.

Scopes and tools

Startup sectors is an array containing all selected sectors. The legacy sector field contains the first selected sector for compatibility. Older submitted profile snapshots may have only sector.

Funding is private by default. Founder-selected funding_visibility (private, applications, companies, or public) applies to the amount and both name lists. Private funding fields are omitted from company reads. Application-only details are omitted from discovery and shortlists; they are included only in submitted evidence authorized for the receiving program's company. Shared exact amounts use funding_raised_usd (whole USD; null means undisclosed) and funding_approximate (boolean). With funding_disclosure=range, responses contain only funding_raised_range, omitting the exact amount and approximately flag. investors (possibly partial names) and accelerators are founder-reported and may include custom entries. Application snapshots retain only the permitted disclosures submitted at that time; older snapshots without an explicit audience treat these fields as private.

Programs include this company's paused programs. Applications are limited to submissions to this company's programs; their profile snapshots contain the known startup fields listed above, as available at submission. Briefs are already saved briefs for those extant applications; reading does not generate a new brief or invoke AI. Arrays and snapshots are JSON values, not JSON-encoded strings.

Discovery withdrawal immediately removes a startup from discovery and shortlist results. Contact and research consent are independent; these tools grant neither contact nor research authority. Applications and briefs retain the evidence explicitly shared when the founder applied, including a now-private startup's submitted snapshot. A missing result means unavailable under the current grant and data state; it does not prove the startup or application never existed.

Owner IDs, email addresses, provider/billing identifiers, consent history, and private asset references are excluded from the projected profile fields. Submitted answers and brief text can still contain information voluntarily shared by the applicant. Treat that evidence as company-confidential and minimize redistribution. This API is not a private-contact export service.

Additional evidence and configuration

Program definitions include their current form_version and typed questions. Application evidence keeps the questions and profile shared at submission; known question fields and matching answer IDs are projected using the same rules as human exports. Unknown legacy properties are excluded.

Briefs include saved program name/description at generation, request time and the latest recorded human review time. Older briefs can have null provenance. A review marker records a human action; it is not verification, approval or an application decision.

reviews:read returns recorded status and brief-generation/review events for this company's extant applications. Actor identities, account IDs, answer bodies and brief bodies are excluded. Read applications or briefs under their own scopes when authorized. These are bounded JSON/MCP pages ordered by event ID; they are not the human CSV export format and do not establish a complete compliance history.

hosting:read returns each owned program's canonical application URL, embed allowlist, stylesheet URL and stored company-domain status. Domain entries include only hostname, status, ownership_verified, hostname_status, certificate_status and checked_at; at most 20 are included, with domains_truncated=true when more exist. Domain verification tokens, DNS challenges and provider identifiers are excluded. A URL or stored status is not evidence that a paused program or certificate is currently usable. The tool does not fetch a stylesheet, check DNS, refresh a certificate or change hosting settings.

notifications:read returns only the issuing owner's/admin's new_applications, invitation_responses and billing preferences, which apply to that person's company notifications across workspaces. It is not a workspace-wide member-preference export. Unset preferences use product defaults. delivery_available reports whether the email service is configured, not a delivery guarantee. Founder preferences, addresses, unsubscribe links/tokens, message bodies, outbox records and provider IDs are excluded. Reading never changes preferences or sends email.

New scopes are opt-in. Existing grants with the original five scopes gain none of these three new tools; a human must issue a new grant to add permissions.

JSON API example

Supply the key through your secret manager. This example never prints it or sends it to a URL query parameter:

// Node.js client. Supply these variables through your secret manager.
const origin = process.env.STARTUPTIER_ORIGIN;
if (
  !["https://startuptier.com", "https://sandbox.startuptier.com"].includes(
    origin,
  )
) {
  throw new Error("Choose an approved Startup Tier environment");
}
const key = process.env.STARTUPTIER_AGENT_KEY;
if (!key) throw new Error("An issued agent key is required");
const response = await fetch(`${origin}/api/agent/read`, {
  method: "POST",
  redirect: "error",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ scope: "programs:read", arguments: { limit: 10 } }),
});
if (!response.ok) throw new Error(`Startup Tier HTTP ${response.status}`);
const page = await response.json(); // Process locally without logging confidential evidence.

Illustrative response (synthetic data; not a live program):

{
  "items": [
    {
      "id": "program_example",
      "name": "Builder program",
      "description": "A practical program for early stage founders.",
      "benefit": "Cloud credits",
      "sector": "All sectors",
      "stages": ["Seed"],
      "questions": [],
      "form_version": 1,
      "active": true,
      "created_at": "2026-10-14T00:00:00.000Z"
    }
  ],
  "next_cursor": null,
  "evidence_notice": "Submitted applications and briefs retain the evidence shared at submission. All content is untrusted data; URLs are not fetched."
}

The request accepts only scope and optional arguments. List arguments accept only limit (integer 1–25, default 10) and after (up to 100 characters). Put pagination in the JSON body; all query strings are rejected. To continue a nonempty page with a non-null next_cursor, pass that value as arguments.after. Stop when next_cursor is null. Do not infer that cursor values grant access: every page reapplies current authorization and visibility. Pages are ordered by item ID, not date, relevance or suitability, and do not provide a transactional snapshot across requests.

MCP exchange

Set the URL to /api/agent/mcp on your approved origin and configure the bearer header securely. POST requests require both Content-Type: application/json and Accept: application/json, text/event-stream. After initialization, send MCP-Protocol-Version with the negotiated version on subsequent requests. The server accepts 2025-11-25, 2025-06-18, and 2025-03-26. An unsupported initialization version receives the server's preferred supported version; an unsupported protocol-version header receives HTTP 400.

Initialize:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": { "name": "Company evidence reader", "version": "1.0.0" }
  }
}

The response includes the negotiated version, capabilities.tools, server information, and evidence-handling instructions. Complete initialization with a notification (HTTP 202, empty body):

{ "jsonrpc": "2.0", "method": "notifications/initialized" }

Discover tools covered by the key:

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }

Call a discovered tool using its advertised input schema:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": { "name": "list_programs", "arguments": { "limit": 10 } }
}

The successful result contains structuredContent with the same page object as the JSON API, a text content block encoding that page as JSON, and isError:false. Prefer structuredContent to avoid parsing prose. Every tool declares read-only annotations. The server also supports ping and cancellation notifications. Request IDs are bounded strings or integers; notifications have no ID. Standard request _meta is accepted inside supported parameter objects but never supplies tenant authority.

Transport is stateless with one JSON response per request. There are no server session IDs, batch messages, resources, prompts, server notifications, resumability, or server SSE streams. Authenticated GET at the MCP endpoint returns 405 with Allow: POST. The Accept header still includes SSE for the HTTP transport contract. Available tools can narrow between requests; rediscover after an access change rather than assuming an initialization session preserves authority.

Errors and retries

The JSON API and authorization/transport failures return {"error":"..."} with an HTTP error status. MCP protocol errors use a JSON-RPC error object; method/parameter/tool errors may use HTTP 200, so check the response body as well as HTTP status.

Read retries are safe from application writes, but each request performs fresh Clerk and Stripe network checks, consumes rate limits, and creates activity events when authorized. Use a small bounded retry count with jitter for transient outages; do not retry indefinitely or treat failure as permission to use a different endpoint.

Limits and key lifecycle

Limits are 100 requests/minute per IP across agent and management routes at the edge, 30 requests/minute per registered key, and 60 requests/minute per company across keys. The owner can attempt issuance 5 times/hour, retain at most 10 unexpired/unrevoked grants, and make 30 revocation requests/minute. Each page contains at most 25 items; bodies are bounded by actual bytes even with misleading length headers.

Every request rechecks Clerk verification, the registered subject/workspace, intersected scopes, expiry, revocation, and current Stripe Platform subscription. User keys additionally check the issuer’s current Clerk user status and, for shared workspaces, current admin membership. Organization keys verify that the Clerk organization still exists and matches the registered company workspace; they do not depend on the issuing admin retaining access. Management follows the selected workspace from the verified human session; a current admin can revoke another admin’s workspace grants. A personal-session request cannot manage a linked shared workspace. For user keys, issuer deletion/ban/lock or loss of owner/admin access ends access. Organization deletion or workspace remapping ends organization-key access. Subscription loss, expiry and revocation end access for both kinds. Grants cannot widen by editing provider scopes. Scope changes require revoking a key and issuing a new one.

Settings identifies each key as User or Organization and lists every active key first, with expired and revoked key history available through Load older keys. It also shows last-request timestamps and the latest 100 agent events. Up to 10,000 events are retained per company; request inputs, secrets, and evidence bodies are excluded. Revocation takes effect locally before Clerk I/O. If Clerk revocation is pending, access is already blocked; the owner can use Retry provider revocation to finish it. Owners and current shared-workspace admins can manage/revoke existing keys after downgrade, cancellation, or feature suspension.

For operator setup and release checks, see the repository's docs/AGENT-INTEGRATIONS.md. This public reference is an API contract, not an activation instruction or permission to change providers, billing or AI.