The REST gateway and API keys

For server-side code, Lovable, n8n and Zapier: call 11 tools with a scoped, expiring, revocable API key. Keys are shown once, stored as hashes, and rate-limited.

Updated 2026-10-13

The gateway is at https://pythe.app/api/cofounder. It also speaks MCP JSON-RPC to clients that send an API key, but the recommended route for MCP clients is OAuth at /mcp.

Make a key

Open Deploy. Choose your client, then the REST API method. The page has a Create a least-privilege key step.
Name it and choose scopes. Start with Read context. Add write scopes only when the workflow needs them.
Choose an expiry. From 1 to 365 days, or never. The default is 90 days.
Copy the key. It looks like pk_live_… and is shown once. Only a hash and a short prefix are stored.

Scopes

Scope	Label in the app	Allows
`read_context`	See roadmap and company context	`get_founder_context`, `get_next_task`
`author_content`	Draft posts, emails, and build prompts	`draft_build_prompt`, `draft_agent_instructions`, `write_linkedin_post`, `draft_email`
`run_actions`	Research and send approved emails	`run_research`, `recommend_integrations`, `get_connection_guide`; and sending with `draft_email`
`manage_tasks`	Save results into the Pythe Library	`save_document`, `edit_roadmap`

Call a tool

Read the company
curl --fail-with-body -X POST "https://pythe.app/api/cofounder" \
  -H "Authorization: Bearer YOUR_PYTHE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"get_founder_context","input":{}}'

List the tools your key can use
curl --fail-with-body -X POST "https://pythe.app/api/cofounder" \
  -H "Authorization: Bearer YOUR_PYTHE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"list_tools"}'

A successful call returns { "ok": true, "result": { "text": "…", "data": … } }. A failure returns { "ok": false, "error": "…" } with HTTP 400. Another action, diagnostics, reports the server, version, credential type, whether the workspace and context are ready, the product name, scopes and tool count.

The 11 REST tools

Tool	Scope	What it does	Main inputs
`get_founder_context`	read_context	Live company context: product, stage, current milestone, positioning, target customer, top tasks, and the milestone ids `edit_roadmap` takes. Call it first.	none
`get_next_task`	read_context	The most important next tasks from the live roadmap, with the what, why and impact.	`limit` (default 3, max 6)
`run_research`	run_actions	Live web research with a cited briefing.	`query` (required)
`draft_build_prompt`	author_content	A paste-ready build prompt grounded in the company, for Lovable, Cursor, v0, Bolt or generic.	`goal`, `target_tool`, `use_next_task`
`draft_agent_instructions`	author_content	A structured instruction block that primes any downstream model for a goal.	`goal`, `target_model`
`write_linkedin_post`	author_content	A finished LinkedIn post in the founder’s voice.	`topic`, `angle`, `tone`
`draft_email`	author_content	An email draft in the founder’s voice. Can send it if the key also has `run_actions`.	`intent`, `to`, `points`, `send`
`save_document`	manage_tasks	Saves a document, plan, prompt or briefing to the Library.	`title`, `content`, `kind`
`edit_roadmap`	manage_tasks	Edits the live plan: status, fields, steps, milestones and graduation criteria, applied in order.	`explanation`, `operations[]`, `roadmap_id`
`recommend_integrations`	run_actions	Which third-party apps to connect for a job, ranked for your stage, with a connection route.	`goal`, `use_next_task`, `platform`
`get_connection_guide`	run_actions	Exact steps for linking an app into a platform.	`app`, `platform`

Limits and credits

Rate limit: 60 calls per minute per key. Over it, the response is HTTP 429 with Retry-After: 60.
Credits: every tool call is metered against the founder’s plan like in-app use. Listing tools, initialising and ping are free so an out-of-credits founder can still attach the connector and see why. Out of credits, a REST call returns the 402 and an MCP call gets a JSON-RPC error that reaches the founder in chat.
Workspace: a key can be tied to one workspace, and access is re-checked on every request.

Manage keys

On the Deploy page, under Keys, you can rotate a key (the new value is shown once and the old one stops working), change its name or scopes, revoke it, run diagnostics, and see its recent activity: tool, transport (MCP, REST or diagnostic), status and error code. Every call is recorded.

Previous: Results, polling and errors · Next: Protocol notes for developers