v1

latestOpenAPI 3.1.02026-07-13250151.3 KB

intents

Create a new intent spec (status defaults to draft) under a product in the authenticated workspace.

Rate-limited by the 'intents' bucket (200/h sliding window, keyed user:<userId> or ip:<ip>). Billing-gated: when the workspace intent quota is reached, returns 403 with body { error: 'plan_limit_reached', metric: 'intents', current, limit, plan }. New intent always starts at status 'draft', version 1. Fires a Slack 'intent_status_changed' notification and an 'intent_created' analytics event (both fire-and-forget). Response is built from a re-fetch with relations (INTENT_WITH_RELATIONS_SELECT) so edgeCases are populated; evidenceIds empty on a fresh create.

post/api/v1/intents

Query parameters

workspace_idstring

Required ONLY for cookie-session auth; identifies the target workspace. Ignored for API-key auth.

Request body

titlestring required

Non-empty after trim. Stored as user_goal.

objectivestring required

Non-empty after trim.

productIdstring required

Non-empty after trim. Must reference a product in this workspace or returns 404.

outcomesstring[]

Strings or structured objects; strings must be non-empty after trim. Normalized to StructuredOutcome[] at the boundary.

constraintsstring[]

Coerced to trimmed non-empty strings.

healthMetricsstring[]

Coerced to trimmed non-empty strings.

edgeCasesstring[]

Each field non-empty after trim. Synced via replaceIntentEdgeCasesRpc; on failure the just-created intent is deleted and 500 returned.

verificationobject

Verification plan object; defaults to {} if omitted.

problemSeverity'low' | 'medium' | 'high' | 'critical'

Optional severity enum.

scopestring

Optional scope object; may be null.

Response

Created — returns the full mapped intent

object required