---
title: "Log an implementation note against an intent."
method: POST
path: "/api/v1/intents/{id}/notes"
tags: ["notes"]
---

# Log an implementation note against an intent.

`POST /api/v1/intents/{id}/notes`

Rate-limited by the 'general' bucket (300/h sliding window, keyed user:<userId> or ip:<ip>). The created row's created_by is set to the authenticated userId, but the POST response does NOT echo createdBy (only id, intentId, note, source, createdAt). The GET list response DOES include createdBy.

## Path parameters

- `id` string, required

## Query parameters

- `workspace_id` string

## Request body

- object
  - `note` string, required — Non-empty after trim.
  - `source` 'mcp' | 'cli' | 'github' | 'manual' | 'verification_checkpoint' | 'linear' | 'jira' | 'execution_sync' — Origin of the note; defaults to 'manual' when omitted.

## Response `201`

Created — returns { id, intentId, note, source, createdAt }

- object

## Other responses

- `400` — Invalid request body (zod) — { error, details }; OR cookie-session auth missing workspace_id
- `401` — Invalid/expired API key, or no Bearer key and no valid session cookie
- `403` — Lacks write scope; OR cookie auth not a member of the workspace
- `404` — Intent not found within this workspace
- `429` — Rate limit exceeded (general bucket, 300/h) — { error } with Retry-After header
- `500` — DB error creating note or unexpected internal error

---

[API](https://skmtc.dev/pathmode/apis/pathmode-api.md) · [All operations](https://skmtc.dev/pathmode/apis/pathmode-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pathmode/pathmode-api/revisions/e419abb0a327/schema)