← Back to app

Developer API

Programmatic access to Ideavory-ai planning. Send a goal, get clarifying questions and a structured action plan back. Available on the Developer plan.

Base URL https://your-domain
Authentication Authorization: Bearer YOUR_API_KEY
Rate limits 30 req/min and 500 req/day per key.
Model all API requests run on gpt-4o-mini (fast, low-cost).

1. Get an API key

Subscribe to the Developer plan, then open the app, click your account → Generate API key. Each new key revokes the previous one — store it somewhere safe.

POST /auth/dev-api-key
X-Auth-Token: <your web session token>

Response:

{
  "api_key": "ai_live_AbCdEf1234..."
}

2. Start a planning session

POST /api/v1/clarify

Send a free-form idea. The model will reply with either clarifying questions or a full action plan.

Request body

Field	Type	Description
`idea`	string	Required. The user's goal in any language.
`idea_objective`	string	Optional context: `company`, `personal`, `career`, `side_project`, `learning`, `creative`, `health`.
`aim_success`	string	Optional primary goal: `money`, `portfolio`, `launch`, `validation`.
`category`	string	Optional legacy topical tag; combined with `idea_objective` when both are sent.
`plan_mode`	string	`fast`, `smart`, or `auto`. Default `auto`.
`model`	string	Ignored on the API — all requests use `gpt-4o-mini`.
`images`	array	Optional. Up to 6 image attachments as `{"data_url": "data:image/png;base64,..."}`.

Example (curl)

curl -X POST https://your-domain/api/v1/clarify \
  -H "Authorization: Bearer ai_live_AbCdEf1234..." \
  -H "Content-Type: application/json" \
  -d '{
    "idea": "Launch a SaaS for freelancers to track invoices",
    "idea_objective": "company",
    "plan_mode": "smart"
  }'

Response

{
  "session_id": "9f1d2c...",
  "reply_kind": "questionnaire",
  "payload": {
    "_kind": "questionnaire",
    "intro": "Quick draft based on your goal.",
    "plan_preview": "Phase 1 ...",
    "questions": [
      {"prompt": "Solo or team?", "options": ["Solo", "Team"]}
    ]
  },
  "model": "gpt-4o",
  "plan_mode": "smart",
  "resolved_plan_mode": "smart"
}

Save the session_id — you'll need it to continue the dialog. reply_kind is questionnaire, plan, or text. When it becomes plan, payload.phases contains the structured action plan.

3. Continue the dialog

POST /api/v1/clarify/reply

Field	Type	Description
`session_id`	string	Required. From the previous response.
`message`	string	The user's next message (answer to a question, follow-up, etc).
`idea_objective`	string	Optional; same tokens as `/clarify` — prepended to the message for the model.
`aim_success`	string	Optional; same tokens as `/clarify`.
`images`	array	Optional, same shape as above.

Example

curl -X POST https://your-domain/api/v1/clarify/reply \
  -H "Authorization: Bearer ai_live_AbCdEf1234..." \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "9f1d2c...",
    "message": "Solo, budget under $500/mo"
  }'

Errors

Status	Meaning
400	Bad input (missing idea, malformed image, message limit reached).
401	Missing or invalid API key.
403	API key belongs to a non-Developer account.
404	Session id does not exist (server restarted or expired).
429	Rate limit reached. Honour the `Retry-After` header.
5xx	Upstream model or server error. Retry with backoff.

Limits per Developer key

30 requests / minute (burst).
500 requests / day (sustained).
120 messages per session_id (one "idea").
6 image attachments per message, max ~5 MB each.
All API requests run on gpt-4o-mini for predictable latency and cost.

Need help?

Found a bug or want a feature? Use the in-app feedback form, or email support.