API reference
Read saved Kitecraft evidence from your configured server.
Resumable onboarding
GET /api/v1/onboarding returns the account’s current step, actual readiness, project ID and nextAction. It makes no provider calls. POST /api/v1/onboarding/advance accepts { "step": "connections" }, questions, visibility or plan. Optional acknowledgments persist; completion requires a real ready plan. A write key is required, and missing prerequisites fail rather than inventing progress.
The sequence is trial → website → analysis → optional connections → optional questions → optional visibility → opportunity research → plan review. Use the existing project, analysis, Google/PostHog, question, visibility and plan endpoints to do the work. Signup, checkout and OAuth consent remain ordinary customer browser actions at /onboarding. The agent never handles payment details or grants consent. Reads, reloads and acknowledgments do not buy research.
Authentication
Project, profile, inventory, Google, and market endpoints accept account-scoped developer keys via Authorization: Bearer TOKEN. Use read-only keys for inspection. Cookie-only account and billing endpoints require the owner's browser session. A developer key does not replace Google OAuth consent.
Set KITECRAFT_API_URL to https://kitecraft.ai for production. For local verification or a supplied preview origin, set it to that origin instead, such as http://127.0.0.1:3100. Obtain project IDs through GET /api/v1/projects. Keep tokens out of URLs and logs.
curl --fail-with-body "$KITECRAFT_API_URL/api/v1/market/$PROJECT_ID" \
-H "Authorization: Bearer $KITECRAFT_API_KEY"Reads return saved data without provider calls. Refresh and sync operations queue work; read status afterward. Writes need an active trial or subscription and an account-owned project. Failed reads return an error status, never an empty success.
To connect an agent, copy the setup prompt on the documentation home.
Request protection and activity
API, CLI and MCP requests share the same account limits across all developer keys: 240 total requests, 60 writes and 6 research starts per minute. A research start consumes all three limits. Dashboard research actions share these limits too. These abuse protections are separate from your billing-period research and audio allowances.
A throttled request returns HTTP 429, a RateLimited error and Retry-After seconds. Check RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until reset) on admitted account requests. Wait before repeating a request. After an interrupted write, read saved status before starting research again.
Open Activity and usage from your account menu to see current allowances and the latest 50 operations. Developer keys show their last authenticated use. History shows safe operation metadata from the last 90 days; request bodies, credentials, article text and transcripts are excluded.
Market themes research
Save editable research themes without provider calls:
POST /api/v1/market/:id/themes with { "themes": [{ "label": "...", "rationale": "...", "seeds": ["seed1"] }] }. One to three themes with distinct labels. Needs write access. Returns { "accepted": true }.
POST /api/v1/market/:id/competitors with { "domains": ["example.com"] }. Saves up to three known business domains as context for the next research run, excluding your own website. Needs write access. Returns { "accepted": true }.
Questions to monitor
GET /api/v1/questions/:id is free of provider calls. It returns saved candidates, recommendations, selection, and run state.
POST /api/v1/questions/:id/generate runs one paid suggestion with no automatic retry. Needs a saved business profile and write access. Returns { "accepted": true }. Poll status until ready or failed.
POST /api/v1/questions/:id/select saves up to ten selected IDs atomically with the current selection version. POST /:id/edit, /api/v1/questions/:id/add, and /api/v1/questions/:id/archive manage questions with revision checks. Needs write access. Returns { "accepted": true }. See Monitor questions.
Visibility checks
GET /api/v1/visibility/:id is free of provider calls. It returns run summaries with answered, pending, and failed counts.
POST /api/v1/visibility/:id/start queues one bounded paid check and returns { "runId": "..." } immediately. Poll status or GET /api/v1/visibility/:id/runs/:runId until terminal; partial runs keep successful answers. GET .../observations/:observationId reads one saved answer. POST .../runs/:runId/cancel stops further paid submissions. Needs write access. See Visibility checks.
POST /api/v1/market/:id/refresh queues one research run with no automatic paid retries. Returns { "accepted": true }. Poll GET /api/v1/market/:id until status is complete or failed.
GET /api/v1/market/:id is free of provider calls. It returns your saved themes, competitors, report, status, and message. Public reports never include internal costs or task IDs.
All endpoints
Use the supplied server origin as KITECRAFT_API_URL, such as http://127.0.0.1:3100 for local verification. Send Authorization: Bearer KITECRAFT_API_KEY from your secret store. Keep keys out of URLs and logs. Download the complete OpenAPI JSON for tooling.
Next content batch
POST /api/v1/plans/:id/extend accepts expectedRevision and the optional strategy, outcome evidence, timezone and cadence fields supported by initial planning. It returns a PlanSnapshot. An active account and write key or owner session are required. It preserves the saved plan during research and failure, and retains previous assignments and packets. Completed repeat requests replay the saved result; busy/stale revisions conflict before new research. Read the current revision first.
Interview recordings and transcripts
See Interviews and transcripts for private recording uploads, full transcripts, correction and retry commands. MCP tool descriptions include accepted formats and the CLI/API upload path. brief_read returns current ready materials beside the frozen packet; Markdown-only exports need a separate material_list read.