Sign in
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 }. A v1 API create is agent-authored: it starts at status 'draft', version 1, origin 'agent', and authorization 'pending'; the response notice tells the caller not to implement until a signed-in human authorizes it. 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

idstring

Adopt this UUID instead of minting one. Exists so a spec keeps its identity when it moves from a local file into a workspace: a keyless author may already have stamped intent/<uuid> on a branch, and a changed id would silently stop the merge webhook resolving it. Rejected with 409 INTENT_ID_TAKEN if the id already exists.

titlestring required

Non-empty after trim. Stored as user_goal.

objectivestring required

Non-empty after trim.

currentStatestring

Author-written as-is behavior: how this works today, before the change (max 4000 chars). Leave out for net-new capability. Distinct from implementationContext, which is analyzer-derived.

productIdstring

Non-empty after trim. Must reference a product in this workspace or returns 404. Omit it and the server resolves it when the workspace has exactly one NON-example product; otherwise the request fails 400 with code PRODUCT_REQUIRED and the candidate list, so the caller can ask and retry with an explicit id. Deliberately strict: workspaces auto-load a demo product, and a per-product GitHub binding decides which repository the PR stamp and merge verification apply to, so a guessed product is a mis-wired verification loop rather than a tidy-up.

constraintsstring[]

Coerced to trimmed non-empty strings.

healthMetricsstring[]

Coerced to trimmed non-empty strings.

edgeCasesobject[]

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

verificationobject

Verification plan object; checks is canonical. The three older buckets are accepted only for compatibility. Defaults to {} if omitted.

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

Optional severity enum.

scopestring

Optional scope object; may be null.

Example request

{
  "outcomes": [
    {
      "measurement": {
        "source": {
          "provider": "posthog",
          "queryRef": {
            "kind": "saved_insight"
          }
        }
      }
    }
  ]
}

Response

Created — returns the full mapped intent

object required

Changes